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 is signed with a public key (JWKS) that can be used to verify the token’s integrity.

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.