Skip to navigation
OAuth API referenceOAuth 2.0

Token endpoint

OAuth 2.0 token endpoint for exchanging authorization codes for tokens or refreshing access tokens.

This endpoint accepts an authorization code (from the authorization endpoint) and returns access tokens, or accepts a refresh token to obtain new access tokens without user interaction.

Content-Type: This endpoint requires application/x-www-form-urlencoded. The request body should be form-encoded, not JSON.

Grant Types:

  • authorization_code: Exchange authorization code for access and refresh tokens
  • refresh_token: Refresh an expired access token using a refresh token

Token Lifetimes:

  • Access tokens expire after 14 days
  • Refresh tokens expire after 60 days

Headers

Content-Type"application/x-www-form-urlencoded"Required

Must be ‘application/x-www-form-urlencoded’.

Request

This endpoint expects an object.
grant_typeenumRequired

Either ‘authorization_code’ or ‘refresh_token’ depending on the flow.

Allowed values:
client_idstringRequired
Your application's client ID.
client_secretstringRequired
Your application's client secret.
codestringOptional

The authorization code received from the authorization endpoint. Required when grant_type is ‘authorization_code’.

refresh_tokenstringOptional

The refresh token from a previous token response. Required when grant_type is ‘refresh_token’.

redirect_uristringOptional

Must match the redirect_uri used in the authorization request. Required when grant_type is ‘authorization_code’.

Response

This endpoint returns an object.
access_tokenstring
Access token for authenticating API requests. Valid for 14 days.
expires_ininteger

Token lifetime in seconds (1209599 = ~14 days).

token_type"bearer"
Always 'bearer' for OAuth 2.0.
scopestring

Space-separated list of granted scopes.

id_tokenstringOptional

A JSON Web Token (JWT) that contains information about the user who authenticated with Yoco. Only included if the openid scope was requested. It can be verified using the corresponding public keys published in the JSON Web Key Set (JWKS).

The JWKS are available at the following URLs:

EnvironmentJWKS URL
Sandboxhttps://iam.yocosandbox.com/.well-known/jwks.json
Livehttps://iam.yoco.com/.well-known/jwks.json

The JWT contains several claims, of which the following are the most relevant:

ClaimDescription
subThe unique identifier for the Yoco merchant.
user_idThe unique identifier for the Yoco merchant. It’s the same as sub.
user_nameThe full name of the merchant.
user_emailThe email address of the merchant.
default_business_idThe unique identifier for the merchant’s default business.
business_idsA list of all business identifiers for which the user has administrative access.
authorized_business_idThe unique identifier for the business that the user authorised.

JWT.io is a useful tool for decoding and verifying JWTs.

refresh_tokenstringOptional

Refresh token for obtaining new access tokens. Valid for 60 days. Only included if ‘offline_access’ scope was requested.

Errors

400
O Auth2error Response
401
Unauthorized Error Response