Skip to main content
POST
Authentication is new. These endpoints are served by your application’s issuer, such as https://<name>.auth.didit.me, and never take your Didit API key.
A refresh token works once. Sending a used refresh token again revokes the whole session, so run one refresh at a time for a session and replace all three tokens together. See Refresh tokens.

Body

One of the two grants, chosen by grant_type. The endpoint accepts the fields of both grants and validates every field it receives, so a refresh that also carries a malformed code_verifier gets a field error. Send only your grant's fields; any other field gets unknown_field.

​
grant_type
enum<string>
required
Available options:
authorization_code
​
code
string
required

The code query parameter your redirect_uri received. Check the callback's state before you exchange it.

Maximum string length: 128
Example:

"Vb0bVt4CLlr8ZL0kE5mAxv8gS6R0rW3hYqC1pN7dJ2s"

​
code_verifier
string
required

The PKCE verifier whose S256 hash was the sign-in's code_challenge.

Required string length: 43 - 128
Pattern: ^[A-Za-z0-9._~-]{43,128}$
Example:

"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

​
redirect_uri
string
required

The exact redirect_uri the sign-in started with. It must still be one of the application's redirect URIs.

Maximum string length: 2048
Example:

"https://app.example.com/auth/callback"

​
client_id
string

Optional. When sent, it must equal your application ID, or the request fails with invalid_client.

Maximum string length: 64
Example:

"7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d"

​
scope
string

Optional and accepted from standard OpenID Connect clients. It never widens what the sign-in granted.

Maximum string length: 512
Example:

"openid email"

Response

New tokens for the session.

Tokens for one session. Replace all three together after a refresh.

​
access_token
string
required

ES256 JWT, header typ: at+jwt. Send it as Authorization: Bearer <access_token>. Claims: AccessTokenClaims.

Example:

"eyJhbGciOiJFUzI1NiIsImtpZCI6ImtfOHNKMmRRdlgwbkxyNVRmWWIzSGtQdyIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL3lvdXItYXBwLmF1dGguZGlkaXQubWUiLCJhdWQiOiI3YjBhNmMyZS0zZjQxLTRjOWEtOGQ1NS0xZTJmM2E0YjVjNmQiLCJzdWIiOiIxYzlkOGI4OC0xYmZmLTQzZDEtYWQ3YS04OGIyYmMwMDI0ZTkiLCJzaWQiOiJjOWFiZjZjYy0yZDY0LTRiZjItYjMxZS1hNGQwOWEwNzBhYjEiLCJqdGkiOiJSZ3F1NzE3OWUtbGhKMGJ2VmVELVlnIiwiaWF0IjoxNzkyMjMzNjc0LCJleHAiOjE3OTIyMzM5NzQsInZlbmRvcl9kYXRhIjoidXNlci00MiIsIm9yZyI6bnVsbCwidmVyaWZpZWQiOnt9LCJhbXIiOlsicGFzc3dvcmQiXSwiYWN0IjpudWxsLCJjbGllbnRfaWQiOiI3YjBhNmMyZS0zZjQxLTRjOWEtOGQ1NS0xZTJmM2E0YjVjNmQifQ.AxrqN8Pm-Op-3OayZk8HcvlFQZhozRiOvQ0SgQsGgrz4UNeJlUEeSlq9B8WcYUuM8naRaY5kQt_TUofnsYcyYQ"

​
id_token
string
required

ES256 JWT, header typ: JWT, for your application to read who signed in. Never send it as an access token. Claims: IDTokenClaims.

Example:

"eyJhbGciOiJFUzI1NiIsImtpZCI6ImtfOHNKMmRRdlgwbkxyNVRmWWIzSGtQdyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3lvdXItYXBwLmF1dGguZGlkaXQubWUiLCJhdWQiOiI3YjBhNmMyZS0zZjQxLTRjOWEtOGQ1NS0xZTJmM2E0YjVjNmQiLCJzdWIiOiIxYzlkOGI4OC0xYmZmLTQzZDEtYWQ3YS04OGIyYmMwMDI0ZTkiLCJzaWQiOiJjOWFiZjZjYy0yZDY0LTRiZjItYjMxZS1hNGQwOWEwNzBhYjEiLCJqdGkiOiJNTHRPNHM4SHItQnJrcDd2NTlPV0Z3IiwiaWF0IjoxNzkyMjMzNjc0LCJleHAiOjE3OTIyMzM5NzQsInZlbmRvcl9kYXRhIjoidXNlci00MiIsIm9yZyI6bnVsbCwidmVyaWZpZWQiOnt9LCJhbXIiOlsicGFzc3dvcmQiXSwiYWN0IjpudWxsLCJhdXRoX3RpbWUiOjE3OTIyMzM2NzQsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJlbWFpbCI6InBlcnNvbkBleGFtcGxlLmNvbSIsIm5vbmNlIjoibi0wUzZfV3pBMk1qIn0.avhfDFp_aUV5_1ssYzwDcIA7H6Waf19P0bn5GCg25FhLIZBGIlwc8HiUPGj1j26r21OkP4FQnS_jM1Ho3dHtKQ"

​
refresh_token
string
required

Single-use. It is valid until the session ends, and each refresh returns a new one.

Example:

"N4yZTl6y24YKYq77X_SOrBn1q2Lit81WBQMOay7dq_IVfTnxyY8ZGcJk-6-fcmWW"

​
token_type
enum<string>
required
Available options:
Bearer
​
expires_in
integer
required

Seconds until the access token expires: at most 300, less when the session ends sooner.

Required range: 0 <= x <= 300
Example:

299

​
session_id
string<uuid>
required

The session these tokens belong to, the same value as the sid claim.

Example:

"c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1"