Onfido logo home page
Watch a demo
Get in touch
Arrow back Back to guides

Going live for the first time

Start here

We recommend you read this guide to help us make your initial integration and testing experience as smooth as possible.

API tokens

Billing information

Live checks cannot be requested without valid billing information, so please add billing information to your account in your Onfido Dashboard.

Generate live API tokens

You can generate live API tokens on the ‘Tokens’ page of your Onfido Dashboard.

Make sure to update your production system to use the live token.

Token security

You must never use API tokens in the frontend of your application or malicious users could discover them in your source code. You should only use them on your server.

We highly recommend that you rotate live API tokens when staff members with access to those tokens leave your organisation. You could consider creating a leaver’s process which covers this.

Read more about token security and rotation in the API documentation.

Privacy best practices

We've marked in our API documentation the points where you'll either send personal data to Onfido, or process biometric personal data yourself. For example, if you're integrating to use one of our Facial Similarity reports.

Always make sure you inform your users about this, obtain any necessary permissions, and take steps to ensure that you are meeting your other obligations under applicable data privacy laws.

For more information on how Onfido uses personal data, view our Privacy Policy.

Rate limits

Unless contractually agreed otherwise, the maximum rate in production is 400 requests per minute.

Sandbox requests are rate limited to 30 per minute.

To lower the possibility you'll be rate-limited, we recommend:

  • running non essential or routine batch API jobs outside your peak hours
  • throttling batch jobs
  • implementing an exponential back-off approach for requests essential to your verification process, with an initial delay of 30 seconds
  • prioritising requests that are essential to verify an active user
  • setting up monitors and alerts for error responses on our API

Status page

We manage a status page to keep our customers updated on any ongoing incidents affecting our service.

We recommend you subscribe to updates as you first integrate with Onfido. If you have any questions, please email our Client Support team.

You can select the option to "subscribe to updates" to get real-time updates via:

  • email
  • text message (SMS)
  • webhooks
  • Atom or RSS feed


Read more about webhooks in the API documentation.

Webhook retry mechanism

Upon receiving a webhook notification, you should acknowledge success by responding with an HTTP 20x response within 10 seconds. Otherwise, we will attempt to resend the notification 5 times according to the following schedule:

  • 30 seconds after the first attempt
  • 2 minutes after the first attempt
  • 15 minutes after the first attempt
  • 2 hours after the first attempt
  • 10 hours after the first attempt

We also use circuit breaking for webhooks: if any 5 requests to the same webhook fail in a row, then that webhook will be disabled for one minute.

Update webhook endpoints

Make sure to update webhook endpoints to handle live check/report status update events.