OAuth
OAuth
Sign users into your app with Teamcast and call Teamcast APIs on their behalf — standard OAuth 2.1 authorization code + PKCE.
Teamcast is a full OAuth 2.1 authorization server. Any external application — LinkedIn Recruiter, Workday, your own hiring portal — can register a client, add a “Sign in with Teamcast” button, and then call Teamcast APIs on behalf of the user who just authorized it. Same pattern as “Sign in with Google” / “Sign in with GitHub”.
How the flow works
A step-by-step diagram of the full authorization code + PKCE handshake.
Integrate your app
Code-level walkthrough to add Sign in with Teamcast in under an hour.
Register a client
Configure audience, scopes, redirect URIs, grant types, PKCE.
Endpoint reference
Every /oauth/* endpoint, token claims, error codes, rate limits.
When to use this
| You want to… | Use |
|---|---|
| Let users sign into your app with their Teamcast account | OAuth authorization code + PKCE |
| Call Teamcast APIs on behalf of a specific user | OAuth access token (with the right scopes) |
| Run a headless background job that touches Teamcast | OAuth client_credentials grant (CONFIDENTIAL client) |
| Give a single partner platform API access across all tenants | Platform API key (see API Keys & OAuth) |
How the flow works
At a glance — the standard authorization-code-with-PKCE flow, with Teamcast as the authorization server and your app as the OAuth client:
[Your App] [Teamcast] [Your Backend]
│ │ │
1. user clicks │ │
"Sign in with │ │
Teamcast" ──► GET /oauth/authorize ─► │
│ (state + PKCE challenge) │
│ │ │
│ ◄── 302 /oauth/continue?prt=… │
│ │ │
2. user signs in + consents │ │
│ │ │
│ ◄── 302 redirect_uri?code=…&state=… │
│ │ │
3. your frontend ─────────────── forwards ─────────────────────────►
hands code to your backend │
│ │ │
4. your backend ─── POST /oauth/token ──► │
exchanges code ◄── { access_token, │
for tokens refresh_token, │
│ expires_in } ── │
│ │ │
5. your backend call Teamcast API with Bearer <access_token> │
│ │ │
6. refresh whenever access_token is about to expire — │
always persist the new refresh_token (rotation + reuse detection).
client_secret never touches the browser. Step 4 happens server-to-server, so confidential credentials stay on your backend.Core concepts (one line each)
| Concept | What it means |
|---|---|
| Client | Your app, registered in Teamcast. Has a client_id and optionally a client_secret. |
| Audience | TENANT = bound to a single Teamcast tenant. PLATFORM = accepts users from any tenant (default). |
| Client type | CONFIDENTIAL = server-side with secret. PUBLIC = SPA/mobile, no secret, PKCE mandatory. |
| Scope | A permission the user grants (e.g. interview:read). Your app requests a subset; users approve on the consent screen. |
| Access token | Short-lived signed JWT (RS256, ~15 min) used on every API call. |
| Refresh token | Opaque long-lived token (~30 days) that rotates on every use. Reuse revokes the whole family. |
| PKCE (S256) | Proof Key for Code Exchange — mandatory. Defends against code interception, especially for PUBLIC clients. |
| Consent | Record that user X granted scopes Y to client Z. Saved so we can auto-skip on subsequent authorizations. |
Next steps
Ready to integrate? Go to Integrate your app. Need to register a new client first? Register a client. Looking for the raw endpoint reference? Endpoint reference.
Issuer URL for this environment: https://mayaapi.teamcast.ai. Discovery document at https://mayaapi.teamcast.ai/.well-known/oauth-authorization-server.