OAuth 2.1 with PKCE

For platform integrations, use the OAuth 2.1 authorization code flow with PKCE: you redirect your customer to Talentir's hosted authorization screens, they sign in (or sign up), select or create their team, and consent. Your server then exchanges the code for tokens scoped to that team.

Get an OAuth client

Create it in the dashboard (recommended): go to Settings → OAuth Clients in your Talentir team dashboard, enter a name and your callback URL(s), and you receive a client_id and client_secret (shown once, with copy and download). Clients created there are attributed to your team, which unlocks the partner-program features: teams created through your authorize flow are credited to your platform, and hosted sessions can carry your white-label branding.

Discovery

GET /.well-known/oauth-authorization-server/api/auth

This returns the authorization_endpoint, token_endpoint, registration_endpoint, and jwks_uri.

Requirements

code_challenge / code_challenge_method=S256 — PKCE is mandatory.
resource=<base_url>/api/v2 on both /authorize and /token, so the token's aud claim binds to the API resource (for production: https://www.talentir.com/api/v2). v2 also accepts a token bound to /api/v1, so an existing integration keeps its tokens while it migrates.
The user must select a team during authorization; the chosen team is encoded in the https://talentir.com/oauth/team_id claim.
Include offline_access in the scope list to receive a refresh token.

Authorization hints

Add any of these query parameters to the /authorize request to pre-fill the hosted screens when you already know who is connecting. They are hints only — the authenticated account and the selected team are always verified server-side.

Parameter	Value	Effect
`login_hint`	Email address	Pre-fills the email and emails the one-time sign-in code automatically (social/passkey sign-in is hidden). If the user is already signed in with a different email, they are asked to switch accounts first.
`team_hint`	The UUID part of a team `id` from `GET /team` (without the `team_` prefix)	Pre-selects that team on the team step. Ignored if the signed-in user is not a member of it.
`team_name`	String	Pre-fills the suggested name when a new user who has no team yet is prompted to create one.

Example (URL-encode the values in practice):

https://www.talentir.com/api/auth/oauth2/authorize?response_type=code&client_id=<client_id>
  &redirect_uri=<redirect_uri>&scope=team:read payouts:write counterparties:write
  &code_challenge=<challenge>&code_challenge_method=S256
  &resource=https://www.talentir.com/api/v2
  &login_hint=creator@example.com
  &team_hint=4399dd07-cf1b-414b-bfbc-91a88dd73ec5

Teams created during your authorize flow are automatically attributed to your platform when your OAuth client was created in the dashboard. Partner-program enrollment (referral terms, white-label) is handled by Talentir — contact us to enroll.

Scopes

See Scopes and permissions for the full table.

Try OAuth from the console

Open an endpoint in the API reference and select Test to use the Scalar API client. You need a client_id to run the OAuth flow. The quickest way for testing is a throwaway dynamically registered client:

curl -sX POST https://sandbox.talentir.com/api/auth/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Talentir API Docs",
    "redirect_uris": ["https://sandbox.talentir.com/api/v2"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"]
  }' | jq

Copy the client_id from the response, open the console, click Authorize, paste it, and run the flow. Docs-testing clients are dynamically registered, so they are anonymous — no attribution or platform branding.