AuthenticationOAuth 2.0

Obtaining tokens

Exchanging authorization code for tokens

Once you receive the authorization code, exchange it for the id_token, access_token and refresh_token.

Obtain token endpoint

EnvironmentToken URL
Sandboxhttps://iam.yocosandbox.com/oauth2/token
Livehttps://iam.yoco.com/oauth2/token

Request

1POST /oauth2/token
2Content-Type: application/x-www-form-urlencoded
3
4grant_type=authorization_code
5&code=AUTHORIZATION_CODE
6&client_id=YOUR_CLIENT_ID
7&client_secret=YOUR_CLIENT_SECRET
8&redirect_uri=YOUR_REDIRECT_URI

Response format

Successful token exchange returns:

1{
2  "access_token": "<ACCESS_TOKEN>",
3  "expires_in": 1209599,
4  "id_token": "<ID_TOKEN>",
5  "refresh_token": "<REFRESH_TOKEN>",
6  "scope": "offline_access openid business/orders:read",
7  "token_type": "bearer"
8}

The id_token is only included if your application requested the openid scope.

id_token

The id_token is a JSON Web Token (JWT) that contains information about the user who authenticated with Yoco.

It can be verified using the corresponding public keys published in the 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; the following are the most relevant:

ClaimDescription
subThe unique identifier for the Yoco merchant.
user_idThe unique identifier for the Yoco merchant. It is 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.

access_token

The access_token is used to authenticate requests to the Yoco API.

This token is a secure credential, and must be stored securely.

refresh_token

The refresh_token is used to obtain a new access_token without requiring the user to re-authenticate.

It is obtained when the offline_access scope is requested.

This token is a secure credential, and must be stored securely.

At this stage, the OAuth flow is complete!

You now have the necessary tokens to make authenticated requests to the Yoco API.