3. Make your first API request

To make your first API request, complete the initial setup, following this high-level procedure:

1. Generate and upload your certificate to authorize your application to access your Revolut Business account via the Business API.
2. Provide a client assertion JWT to obtain a signing key.
3. Consent to the application in the Revolut Business app to obtain an authorization code.
4. Exchange authorization code for access token to authenticate your requests to the Business API.
5. Try your first API request to get a list of all your accounts.

After you complete and validate the setup, you can make requests to the Business API. If you encounter issues, such as your access token has expired, see the Troubleshooting section.

1. Add your certificate​

Authorize your application to access your Revolut Business account via the Business API. To do this, first generate your certificate and upload it on the Business API settings page of the Revolut Business app.

Generate a private and a public certificate​

To generate the certificates, you need a Command Line Interface (CLI), for example, Terminal on macOS. For Windows, we recommend that you install WSL to run the commands.

1. Open your preferred CLI.

2. In your CLI, navigate to the directory in which you want to save the certificates.

   cd <INSERT_DIRECTORY>
   

3. To create a private and a public certificate, paste this command in your CLI and press Enter.

   openssl genrsa -out privatecert.pem 2048
   openssl req -new -x509 -key privatecert.pem -out publiccert.cer -days 1825
   

   You will be asked to enter some details about your organization for the certificate's "Distinguished Name". The prompts below will appear line by line.

   Country Name (2 letter code) []:
   State or Province Name (full name) []: 
   Locality Name (eg, city) []:
   Organization Name (eg, company) []:
   Organizational Unit Name (eg, section) []:
   Common Name (eg, fully qualified host name) []:
   Email Address []:
   

   Enter each piece of information and press Enter until you get back to the command prompt.

   Optionally, you can leave some fields blank. However, for the public certificate to be generated successfully, you must enter at least one piece of information, for example, Country Name.

cat publiccert.cer

Copy the whole contents of the public certificate and leave the CLI open. You'll need them both in later steps.

Upload your certificate​

To upload the generated certificate, copy and paste the content of publiccert.cer into the required field.

1. Go to the API settings.

   Revolut Business 4Revolut Business 5
   ProductionSandbox

   Log in to the Revolut Business web app, and go to the Business API settings.

   To open the settings manually

   In the web app, click on the gear icon in the top right corner. Then, go to APIs → Business API.

2. In the API Certificates section, click Add API certificate to add your first certificate.

   If you already have other certificates added, click Add new.

3. Copy and paste the content of publiccert.cer to the X509 public key field.

   caution

   Make sure that you copy the whole output, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

4. Specify the OAuth redirect URI (in this example we use: https://example.com).

   This is the URL where you are redirected after you consent for the application to access your Revolut Business account. You must use the same domain here and in the iss parameter provided in substep 3 of Generate a client assertion.

   For testing purposes, you only need it to retrieve the code parameter from this URL later, so you can use any URL.

5. Give your certificate a meaningful title. It will help you later to distinguish it from other certificates.

6. Click Continue. This opens the API Certificate details with the parameters of your application.

7. Copy the ClientID shown in those detail. You will need it in the following steps.

2. Generate a client assertion​

In order to grant the consent to your application, you will need to generate a client-assertion JWT (JSON Web Token) which is cryptographically signed with your private certificate generated in step 1.

This JWT will be used whenever a new access token needs to be requested, and it is composed of a header, a payload and a signature.

{
  "alg": "RS256",
  "typ": "JWT"
}

{
  "iss": "example.com",
  "sub": "zfTKV9Eie_XLHl03f2Y7vJYDe5Klr6Y54v8fsp4Gvgp",
  "aud": "https://revolut.com",
  "exp": 1706136791
} 

There are several libraries to generate a JWT. To manually generate the JWT from your CLI, perform the following steps:

1. Go back to your CLI.

   Make sure that you are in the same directory where you saved your privatecert.pem file from step 1. If you want to use a different directory, make sure that you copy the private certificate there.

2. Prepare the JWT header and save it as header.json.

   Save with a CLI commandSave manually
   Paste this command into your CLI and press Enter.

   cat <<EOF > header.json
   {
     "alg": "RS256",
     "typ": "JWT"
   }
   EOF
   

3. Prepare the JWT payload and save it as payload.json. Replace the placeholders in angle brackets (<>) with your own values. Also, make sure that the exp value is a number, not a string.

   Save with a CLI commandSave manually
   Insert your values below to generate the payload. Then, copy and paste the below command into your CLI and press Enter.
   
   
   iss

   sub

   The Client ID (sub) cannot be empty

   exp

   cat <<EOF > payload.json
   {
     "iss": "example.com",
     "sub": "<YOUR_ClientID>",
     "aud": "https://revolut.com",
     "exp": 1739452693
   } 
   EOF
   

4. Generate the signed JWT and save it as client_assertion.txt.

   Run this set of commands in your CLI. Remember to press Enter after pasting, otherwise it might not run fully, resulting in the signature missing.

   # Add encoded and normalised header
   cat header.json | tr -d '\n' | tr -d '\r' | openssl enc -base64 -A | tr +/ -_ | tr -d '=' > client_assertion.txt
   echo -n "." >> client_assertion.txt
   # Add encoded and normalised payload
   cat payload.json | tr -d '\n' | tr -d '\r' | openssl enc -base64 -A | tr +/ -_ | tr -d '=' >> client_assertion.txt
   # Generate signature
   cat client_assertion.txt | tr -d '\n' | tr -d '\r' | openssl dgst -sha256 -sign privatecert.pem | openssl enc -base64 -A | tr +/ -_ | tr -d '=' > sign.txt
   echo -n "." >> client_assertion.txt
   # Add signature
   cat sign.txt >> client_assertion.txt
   

cat client_assertion.txt

3. Consent to the application​

1. Go back to the API settings.

   ProductionSandbox

   Log back in to the Revolut Business web app, and go to the Business API settings again.

2. Select the certificate you want to edit.

3. In the API Certificate details, copy your client ID from the ClientID field.

4. Click Enable access. This takes you to the /app-confirm endpoint where you grant your application access to your account via the Business API. See an example below.
   

   https://business.revolut.com/app-confirm?client_id=<ClientID>&redirect_uri=https://example.com&response_type=code
   
   Optionally

   You can narrow down the security permissions of the consent by adding to this URL the scope query parameter with a comma separated list of the desired scopes as its value.
   For example: (...)&response_type=code&scope=READ,WRITE.

5. Click Authorise. This triggers a 2-factor authentication (2FA) process.

   

   On successful authorisation, you are redirected to the OAuth redirect URI that you specified.

6. Get the authorization code (code) from the redirect URI.

   https://example.com?code=oa_prod_vYo3mAI9TmJuo2_ukYlHVZMh3OiszmfQdgVqk_gLSkU

   caution

   For security reasons, the authorization code is only valid for two minutes.

   If it expires before you use it, you must repeat the substeps 4-6 of Consent to the application to generate a new one.

4. Exchange authorization code for access token​

To exchange the authorization code (code) for an access token (access_token), make the following cURL call, for example, from your CLI:

curl https://b2b.revolut.com/api/1.0/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded"\
  --data "grant_type=authorization_code"\
  --data "code=<INSERT_AUTHORIZATION_CODE>"\
  --data "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer"\
  --data "client_assertion=<INSERT_JWT>"

{
  "access_token": "oa_prod_rPo9OmbMAuguhQffR6RLR4nvmzpx4NJtpdyvGKkrS3U",
  "token_type": "bearer",
  "expires_in": 2399,
  "refresh_token": "oa_prod_hQacSGnwx-luIfj3dlVByrytVV9rWAnyHkpJTwG_Tr8"
}

5. Try your first API request​

To verify that everything is working, make a request to the /accounts endpoint to get a list of all your accounts using the access token which you obtained in the previous step:

curl https://b2b.revolut.com/api/1.0/accounts \
  -H "Authorization: Bearer <your access_token>"

On success, you get a response similar to this one:

[
  {
    "id": "2a0d4d03-e26c-4159-9de1-c6bf3adfd8a1",
    "name": "Current GBP account",
    "balance": 100.0,
    "currency": "GBP",
    "state": "active",
    "public": false,
    "updated_at": "2017-06-01T11:11:11.1Z",
    "created_at": "2017-06-01T11:11:11.1Z"
  },
  {
    "id": "df8d6b20-0725-482e-a29e-fb09631480cf",
    "name": "EUR expenses account",
    "balance": 1234.0,
    "currency": "EUR",
    "state": "active",
    "public": false,
    "created_at": "2017-06-01T11:11:11.1Z",
    "updated_at": "2017-06-01T11:11:11.1Z"
  }
]

Troubleshooting​

Access token expired​

When the access token expires, you won't be able to make successful API calls and will get the 401 Unauthorized error in response:

{"message":"The request should be authorized."}

To regain access, you must first request a new access token using the refresh token (returned in step 4) and the JWT (obtained in step 2).

Get a new access token​

To request a new access token, make the following request.

curl https://b2b.revolut.com/api/1.0/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded"\
  --data "grant_type=refresh_token"\
  --data "refresh_token=<insert refresh_token>"\
  --data "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer"\
  --data "client_assertion=<insert JWT>"

A successful response returns a new access token with its type and expiry time in seconds.

{
  "access_token": "oa_prod_rPo9OmbMAuguhQffR6RLR4nvmzpx4NJtpdyvGKkrS3U",
  "token_type": "bearer",
  "expires_in": 2399
}

Refresh token expired​

While the refresh token has no expiration date, for businesses on the Freelancer plan, the refresh token is terminated every 90 days to ensure compliance to PSD2 SCA regulations. If that's your case, you must re-authorise the API to regain access to your account, and request a new access token.

Re-authorise the API​

To re-authorise the API, go to the Revolut Business app and connect your application again.

1. Open the Revolut Business web app.
2. Go to settings.
3. Go to APIs > Business API.
4. Select your certificate.
5. Click or tap Enable access and continue from substep 5 of 3. Consent to the application.

Client assertion JWT expired​

Similarly to the access token, when you create a JWT in step 2, it also has an expiration date specified in the exp field.

If you refresh the access token with an expired JWT, you will get an error response like this:

{
    "error": "invalid_request",
    "error_description": "The Token has expired on Mon Jun 03 15:55:21 UTC 2024."
}

In this case, you must generate a new JWT by following the instructions in step 2. Make sure to use the same private key as before.

What's next​

• See the API Reference for full details on different endpoints of the Business API.
• Browse our guides to learn how to use various Business API endpoints.
• See the API usage and testing section for developer-specific details.