Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.masker.dev/llms.txt

Use this file to discover all available pages before exploring further.

Masker authenticates API calls using a GitHub OAuth session cookie. There is no password login and no API key issuance today — long-lived scoped tokens are on the May 30 roadmap. Until then, the session cookie is the credential for all /api/v1/* endpoints. When you complete the GitHub OAuth flow, Masker sets a cookie on your browser: 
Set-Cookie: masker_session=<opaque>; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=2592000
PropertyValue
Namemasker_session
HttpOnlyYes — JavaScript cannot read it
SecureYes — HTTPS only
SameSiteLax
Lifetime30 days, sliding — renewed on every authenticated request
DomainBound to the API host
The cookie value is an opaque token. On the server it maps to a session record containing your user ID, GitHub login, and last-seen timestamp. You cannot decode or forge it.

​
Authenticating API requests

Send the cookie value in a Cookie request header: 
curl -H "Cookie: masker_session=ey..." \
  https://masker-voice.fly.dev/api/v1/agents
For scripting and CI, copy the cookie from your browser’s DevTools after signing in to the portal (Application → Cookies → masker_session), then export it as an environment variable: 
export MASKER_SESSION=ey...
curl -H "Cookie: masker_session=$MASKER_SESSION" \
  https://masker-voice.fly.dev/api/v1/agents
This is not the long-term answer for automation, but it works for one-off scripts and CI checks today.

​
The OAuth flow

The OAuth handshake is browser-driven. Masker does not expose an API endpoint that lets you complete it headlessly.
1

Start the OAuth flow

Navigate to GET /api/v1/auth/github. Masker redirects your browser to GitHub’s authorization page.
2

Approve the GitHub request

GitHub asks you to authorize Masker. Once you approve, GitHub redirects back to Masker.
3

Masker completes the exchange

Masker receives the authorization code at GET /api/v1/auth/github/callback, exchanges it for a GitHub access token, creates a session, sets the masker_session cookie, and redirects you to /portal.
For headless automation, complete the OAuth flow in a real browser once, then copy the resulting cookie for use in scripts.

​
Logging out

curl -X POST -H "Cookie: masker_session=ey..." \
  https://masker-voice.fly.dev/api/v1/auth/logout
Returns 204 No Content, clears the cookie, and permanently invalidates the server-side session row. The cookie value cannot be reused after logout.

​
Identifying the current user

curl -H "Cookie: masker_session=ey..." \
  https://masker-voice.fly.dev/api/v1/me
Returns the user record associated with the current session, including your GitHub login and account details.

​
What 401 and 403 mean

  • 401 unauthenticated — The request arrived with no masker_session cookie, or with a cookie that has expired or been invalidated. Sign in again to get a fresh session.
  • 403 forbidden — Your session is valid, but you are not permitted to perform this action. For example, deleting an agent requires admin access; a non-admin user’s request will be rejected with 403.

​
Webhook endpoints

Two endpoints are called by external systems and therefore cannot use the masker_session cookie:
  • POST /proxy/{agent_id}/v1/chat/completions
  • POST /vapi/webhook/{agent_id}
These endpoints use HMAC signature verification instead. The voice platform signs each request with a shared secret; Masker validates the X-Vapi-Signature header against the MASKER_VAPI_WEBHOOK_SECRET environment variable. Configure the same secret value on both sides — a mismatch returns 401.

​
Coming soon

Scoped API tokens are targeting the May 30 release. Tokens will be issuable from the portal with explicit scopes (agents:read, sessions:read, reports:read) and will be the recommended credential for CI and machine-to-machine access. OIDC and mTLS support are on the longer-term roadmap.