Token Endpoint
POST/openapi/v1/oauth/token
Exchange an authorization code, refresh a token, or obtain a server-to-server access token.
Supports three grant_type values:
| grant_type | Use Case | Returns refresh_token? |
|---|---|---|
authorization_code | Exchange auth code for tokens after user authorization | ✅ Yes |
refresh_token | Refresh an expired access_token using a refresh_token | ✅ Yes (new refresh_token, old one invalidated) |
client_credentials | Server-to-server; no user involved | ❌ No |
Rolling refresh: Each
refresh_tokengrant returns a newrefresh_token. The old one is immediately invalidated. Always store the latest value.
Request Parameters
Request Body
application/x-www-form-urlencodedgrant_typeRequiredstring
authorization_coderefresh_tokenclient_credentials
codeOptionalstring
The authorization code returned in the `redirect_uri` callback. Valid for **10 minutes** and can only be used once.
code_verifierOptionalstring
The original PKCE random string generated before opening the authorization URL. The server verifies `base64url(SHA-256(code_verifier)) == code_challenge`.
client_idRequiredstring
Your app's `client_id`.
client_secretRequiredstring(password)
Required for confidential clients; not needed for public clients. Generated when creating the App in the console, shown only once, keep it safe.
redirect_uriOptionalstring
Must exactly match the `redirect_uri` used when initiating the authorization request.
refresh_tokenOptionalstring
The current valid refresh token.
scopeOptionalstring
space_idOptionalstring
The Space (tenant) to act within. The app must be installed in this Space.
Request Example
"grant_type=authorization_code&code=AC_aBcDeFgHiJkLmNoP&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&client_id=SGCLxQk2mN8pR4vW1yH3jT5bZ6aE7cF0&client_secret=Kj3mN8pR4vW1xZ6bY2qT5hE9gA0cF7dLsUr4Qz8P&redirect_uri=myapp%3A%2F%2Foauth-callback"Response Parameters
Response.Data
access_tokenRequiredstring
JWT access token. Valid for 1 hour.
token_typeRequiredstring
Always `Bearer`.
Bearer
expires_inRequiredinteger
Access token lifetime in seconds.
refresh_tokenOptionalstring
Refresh token. Permanent (no expiry). Each use returns a new `refresh_token` (rolling refresh) — store the new value immediately.
scopeOptionalstring
The scopes granted.
Response Example
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "RT_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
"scope": "envelope:create envelope:read"
}Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_request | Missing required parameters |
| 400 | invalid_grant | Authorization code expired or already used |
| 400 | invalid_grant | PKCE verification failed |
| 400 | invalid_grant | Refresh token invalid or already rotated |
| 400 | invalid_scope | Requested scope exceeds granted scope |
| 400 | unsupported_grant_type | Unsupported grant_type |
| 401 | invalid_client | Invalid client_secret |
| 401 | invalid_client | Unknown or suspended client |
| 500 | server_error | Internal server error. |