API Console
Help

3. Make your first API request

Now that you have access to a Revolut Business account, you can obtain an API key and make your first request to the Business API.

Sandbox vs Production

Make sure that you test your integration in Sandbox before going live, and that you use the correct URL for each environment.

If you already have an application set up with the legacy access token flow, see Migrate from the access token flow.

How it works

The Business API lets you manage your Revolut Business account programmatically, for example, to read balances, create payments, and manage cards and counterparties. The API authenticates requests with API keys.

The API Console is where you create and manage the API keys that authenticate your requests, inspect API logs, monitor API activity, and troubleshoot errors.

API keys let you control which products and permissions your integration can access. For extra security, some of them require request signing.

To make your first API request, create an API key and call the /accounts endpoint to get a list of your accounts. The steps in this guide apply to both the Sandbox and Production environments.

Before you begin

Before you start, make sure you have:

  • A Revolut Business account in Sandbox or Production.
  • The following Platform permissions on your account:
    • API & Integrations: Manage Integrations, Manage API
    • Billing: View Business

1. Create an API key

In the API Console, create an API key and select the products and permissions your integration needs. For this flow, you'll need the Accounts product with Accounts Read permissions.

Whether your key requires request signing depends on the products and permissions you select: for example, a key with access to the Accounts product is created with signing keys, so every request with it must be signed.

For the full walkthrough, see the API Console documentation: Create an API key. You can also check which products and permissions add signing keys: Signing requirements.

Test with Sandbox

To try the flow in a test environment without using live data, use a Sandbox account. Sandbox accounts come with pre-generated full-access keys, so you can start testing immediately. For more information, see the API Console documentation: Test your integration with Revolut Sandbox.

2. Make a request

To check that your setup is working correctly, call the /accounts endpoint to get a list of all your accounts.

The request below uses placeholders for the headers. Replace them with the actual values for your request.

Is signing required?

A key created for the Accounts product is created with signing keys, so requests with it must also include the Revolut-Api-Timestamp and Revolut-Api-Signature headers, regardless of the target endpoint. These headers are generated from the request data and the key's private signing key.

To learn how to add the required headers, see the API Console documentation: Make a request.

curl https://b2b.revolut.com/api/1.0/accounts \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Revolut-Api-Timestamp: <your_timestamp_in_ms>" \
  -H "Revolut-Api-Signature: <your_signature>"

On success, you get a list of your accounts.

To call other endpoints, follow the same principles. For more information, see the API Console documentation: Make a request.

Check your results

After you make your request, you can compare the results obtained via API with the Revolut Business app. If you're testing with the Sandbox environment, see the API Console documentation: Test your integration with Revolut Sandbox.

Authenticating with Access Token (deprecated)

The steps below describe the legacy certificate-based flow, in which you upload a certificate, generate a client assertion JWT, and exchange an authorization code for an access token. If you're getting started, use the API key authentication instead.

Migrate from the access token flow

Deprecated

The access token (OAuth 2.0) authentication method is deprecated.

If you're currently using access tokens, migrate to API keys as soon as possible. During the interim period, existing (legacy) API keys remain in the Revolut Business app under Settings → APIs → Business API certificates.

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.

When running commands in the CLI

Remember to press Enter after pasting each command, to make sure each line is executed.

  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.

Expected result

The certificates are generated and saved to the directory you chose in step 2.

To display the contents of your certificate in your CLI, run:

cat publiccert.cer

Alternatively, you can open the certificate file with a text editor and copy its contents from there.

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

To amend the information, rerun the steps above to overwrite the certificate with a new one.

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.

    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 your avatar in the top right corner. Then, go to Settings → APIs.

  2. In the Business API certificates section, click Add new to add a new certificate.

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

    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 details. You will need it in the following steps.

IP whitelisting

Optionally, provide a list of IP addresses for additional security. If provided, only traffic from these IP addresses will be allowed.

Single IP addresses as well as IP pools in CIDR notation are allowed. Make sure that the IPs you provide are not local (i.e. private) IP addresses.

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.

See examples for the header and the payload, and the format of the parameters

JWT Header:

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

JWT Payload:

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

The payload parameters must meet the following format:

FieldDescriptionFormatRequired
issDomain from your OAuth redirect URI (provided in substep 4 of Upload your certificate) without https://.StringYes
subYour client_idStringYes
audhttps://revolut.comStringYes
expJWT expiration date. Example for 90 days in the future: 1706136791. You can use this converter to provide the UNIX timestamp.Number, in UNIX timestamp format, given in secondsYes

Do not provide the exp value as a string!

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.

    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.

    Replace the placeholders in the payload below with your own values, then copy and paste the command into your CLI and press Enter.

    cat <<EOF > payload.json
    {
      "iss": "<your domain without https://>",
      "sub": "<your client_id>",
      "aud": "https://revolut.com",
      "exp": <unix timestamp in seconds>
    }
    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
Expected result

A client_assertion.txt file containing the client assertion JWT is created in your chosen directory.

To display the contents of your JWT in the CLI, run:

cat client_assertion.txt

Never share your client-assertion JWT (JSON web token) and refresh_token with anyone, as these can be used to access your banking data and initiate transactions.

Validate the result

You can validate the JWT that you just generated at jwt.io:

  1. Paste the contents of the client_assertion.txt file into the Encoded Token field.
  2. In the JWT Signature Verification section, paste the contents of the publiccert.cer file into the Public Key field.
  3. Check that the JWT is decoded correctly and the signature is verified.

This only checks if the JWT is well-formed, if the header and payload have been correctly signed, and if the signature matches the provided certificate.

  1. Go back to the API settings.

    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.

    Account access request

    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

    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>"
Request fields (URL-encoded) - details

See what the particular fields mean, how their values should be formatted, and whether they must be included in the request or if they can be skipped:

FieldDescriptionFormatRequired
grant_typeThe OAuth grant type: authorization_code.StringYes
codeThe authorization code obtained from the redirect URI in step 3.StringYes
client_assertion_typeThe type of the client assertion: urn:ietf:params:oauth:client-assertion-type:jwt-bearer.StringYes
client_assertionThe JWT token that you generated in step 2.StringYes
Expected result

A successful response returns the access token with its type and expiry time in seconds, and the refresh token, which does not expire.

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

Every access token is only valid for 40 minutes. After the access token expires, you must request a new one, using the refresh token (refresh_token) and the JWT (client_assertion.txt).

For more information, see the Troubleshooting section: Access token expired.

Migrate to API keys

The access token flow is deprecated. If you're setting up a new integration, create an API key instead: Create an API key. If you already use access tokens, switch to API keys as soon as possible.

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"
  }
]
Success

Congratulations! You're ready to make requests to the Business API with an access token.

Troubleshooting

Access token expired

Migrate to API keys

The access token flow is deprecated. If you're setting up a new integration, create an API key instead: Create an API key. If you already use access tokens, switch to API keys as soon as possible — see Migrate from the access token flow.

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.

Refreshing an access token invalidates the previous token.

This means that if you have an access token that hasn't expired yet and you refresh it with your refresh token, your existing access token will no longer work, and you will need to switch to the new access token.

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>"
Request fields (URL-encoded) - details

See what the particular fields mean, how their values should be formatted, and whether they must be included in the request or if they can be skipped:

FieldDescriptionFormatRequired
grant_typeThe OAuth grant type: refresh_token.StringYes
refresh_tokenThe refresh token.StringYes
client_assertion_typeThe type of the client assertion: urn:ietf:params:oauth:client-assertion-type:jwt-bearer.StringYes
client_assertionThe JWT token that you generated in step 2.StringYes

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
}

Client assertion JWT expired

Migrate to API keys

The access token flow is deprecated. If you're setting up a new integration, create an API key instead: Create an API key. If you already use access tokens, switch to API keys as soon as possible — see Migrate from the access token flow.

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.

Best practices

For security reasons, it is recommended that you provide a short expiration date when generating the JWT, just enough to refresh the access_token. This reduces the risk in the event the JWT gets leaked.

What's next

Rate this page