API requests can be authenticated by passing along an OAuth 2 token.

Simple workflow

Go to and register your app.

From there, you can generate a unique token that will let you access all your protected resources. When your token is created, use it in all of your calls to the API by adding it to the authorization header like this:

Authorization: Bearer <your token>

You can also use it as a query parameter:<your token>

To be more secure, you can integrate in a full OAuth workflow.

OAuth 2

For a full app integration, you wouldn't want to get into the business of asking customers for their passwords, or storing them, so we offer a simple way to ask a user for access to their account. You get an API access token back without ever having to see their password or ask them to copy/paste an API key.

  1. Grab an OAuth 2 library.
  2. Register your app at You'll be assigned a client_id and client_secret. You'll need to provide a redirect_uri: a URL where we can send a verification code. Just enter a dummy URL like if you're not ready for this yet.
  3. Configure your OAuth 2 library with your client_id, client_secret, and redirect_uri. Tell it to use:

          :access_token_path  => "/oauth/token"
          :authorize_path     => "/oauth/authorize"

    and as the base url

  4. Try making an authorized request to to dig in and test it out!

OAuth 2 from scratch

If you're going bare-metal and developing your own OAuth 2 client, you have a bit more work to do.

>> request access, receive a verification code, trade it for an access token.

The typical flow for a web app:

  1. Your app requests authorization by redirecting your user to Launchpad:
  2. We redirect the user back to your app with a time-limited verification code.

  3. Your app makes a backchannel request to trade the verification code for an access token. We authenticate your app and issue an access token:

  4. You get an access token and a refresh token in exchange of the authorization code

  5. Your app uses the access token to authorize API requests to any of the Bime ID's accounts. Set the Authorization request header:

    Authorization: Bearer <tokenhere>
  6. The access token has a time to live of 2 hours. When it becomes invalid, you can ask for a new one thanks to the refresh token you received.

Implementation notes:

  • Start by reading the draft spec
  • We implement draft 5 and will update our implementation as the final spec converges. Be prepared for changes along the way.
  • We support the webserver and useragent flows, not the client_credentials or device flows.
  • We return more verbose errors than what's given in the spec to help with client development. We'll move these to a separate parameter later.
Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk