OAuth

Register a client

Configure a partner application so it can sign users in via Teamcast.

OAuth clients represent external applications that integrate with Teamcast. Each client is registered by a SuperAdmin and receives credentials your app uses to drive the authorization-code + PKCE flow.

Client management is SuperAdmin-only. Tenant admins cannot create, view, or delete clients. End users consent to clients individually via the OAuth flow and can revoke access anytime at /account/connections.

Endpoints

Method	Endpoint	Gate	Purpose
POST	/super-admin/oauth-clients	SuperAdmin	Register a new client
GET	/super-admin/oauth-clients	SuperAdmin	List clients
GET	/super-admin/oauth-clients/:id	SuperAdmin	Get one client (secret never returned)
PATCH	/super-admin/oauth-clients/:id	SuperAdmin	Update mutable fields
DELETE	/super-admin/oauth-clients/:id	SuperAdmin	Delete + invalidate tokens

Client fields

Field	Type	Mutable	Description
name	string (3–255)	yes	Display name shown on the consent screen.
audience	TENANT \| PLATFORM	no	PLATFORM = any tenant's users may sign in. TENANT = only users from the bound tenant. Default: PLATFORM.
clientType	CONFIDENTIAL \| PUBLIC	no	CONFIDENTIAL = issued a secret. PUBLIC = SPA/mobile, no secret, PKCE mandatory.
scopes	string[]	yes	Maximum scopes this client may ever request.
redirectUris	string[]	yes	Exact-match callback URLs. http allowed only for localhost/127.0.0.1.
allowedGrantTypes	string[]	yes	Subset of authorization_code, refresh_token, client_credentials.
tokenEndpointAuthMethod	string	yes	client_secret_basic \| client_secret_post \| none (public only).
requirePkce	boolean	yes	Enforce S256 PKCE at /authorize. Always on for PUBLIC.
accessTokenTtlSeconds	int?	yes	Per-client override (default 900 s).
refreshTokenTtlSeconds	int?	yes	Per-client override (default 30 d).
clientUri / logoUrl / tosUri / policyUri	string?	yes	Consent-screen branding.

Register

The clientSecret is returned once. Store it securely; if lost, delete the client and re-register.

bash

curl -X POST https://mayaapi.teamcast.ai/api/v1/super-admin/oauth-clients \
  -H "Authorization: Bearer <SUPERADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Recruiter",
    "audience": "PLATFORM",
    "clientType": "CONFIDENTIAL",
    "scopes": ["interview:read","interview:create","interview:update","interview:approve","candidate:read"],
    "redirectUris": ["https://app.acme.com/oauth/callback"],
    "allowedGrantTypes": ["authorization_code","refresh_token"],
    "tokenEndpointAuthMethod": "client_secret_basic",
    "requirePkce": true,
    "clientUri": "https://app.acme.com"
  }'

Update

Patch mutable fields. Omitted fields are left untouched. Immutable fields (clientId, clientSecret, audience, clientType) must be changed via delete + re-register.

bash

curl -X PATCH https://mayaapi.teamcast.ai/api/v1/super-admin/oauth-clients/<id> \
  -H "Authorization: Bearer <SUPERADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["interview:read","interview:create","interview:update","interview:approve"],
    "redirectUris": ["https://app.acme.com/oauth/callback","http://localhost:4000/callback"]
  }'

Validation invariants

PUBLIC client

tokenEndpointAuthMethod must be none; requirePkce must be true; allowedGrantTypes cannot include client_credentials.

Redirect URIs

Required whenever authorization_code or refresh_token is an allowed grant. Must be valid URLs; http:// only permitted for localhost and 127.0.0.1. Stored and matched exactly — no wildcards, no path fuzzing.

Delete

Deletes the client record. Access tokens that have already been issued remain valid until their natural expiry; refresh tokens can no longer rotate (client auth fails).

bash

curl -X DELETE https://mayaapi.teamcast.ai/api/v1/super-admin/oauth-clients/<id> \
  -H "Authorization: Bearer <SUPERADMIN_JWT>"

Was this page helpful?

NextIntroduction →