bind.co

Test your integration

Once your application is APPROVED, your developers can sign in and test it end to end on their own data. The first user from outside your developers makes it IMMUTABLE. This page says exactly who can sign in through your application at each review status, and how to run the whole flow on your own data.

bind.co has no sandbox or test mode, by design. Its records come from real inboxes, so a separate environment with made-up data would not show how your integration behaves. Instead, an APPROVED application is tested end to end on its developers' own real inbox, against the live API.

Who counts as a developer

Your application's developers are the people listed as its administrators in the developer portal: the account that created the application, and any administrator added since. An added administrator must have an email address on the application's verified domain.

What each status allows

Status Who can sign in through your application Tokens and API calls
DRAFT Nobody. GET /oauth2/authorize shows the user a bind.co error page (client_not_approved); nothing is sent to your redirect_uri. POST /oauth2/token answers invalid_client.
SUBMITTED (in review) Nobody, as for DRAFT. As for DRAFT.
APPROVED Anyone, starting with your developers. Yes.
IMMUTABLE Anyone. Yes.
SUSPENDED, DELISTED Nobody. Refused: tokens already issued answer 403 access_denied with hint.bind_subcode client_not_approved.

An application that bind.co has switched off cannot start a sign-in or obtain tokens, whatever its status.

GET /v1/oauth2/authorize/preflight answers at every status with your application's credentials. Before approval it stops at the client_status_valid check and skips the checks after it, so run it again once your application is APPROVED to check the whole authorize URL.

Before approval

Until your application is APPROVED, nobody can connect to it, its developers included, so no call reads anyone's data through it. You can still download the API reference and generate a client, and call the routes that take no credentials, such as GET /v1/operations/{operation_type}/schema.

Testing on your own data

Once your application is APPROVED:

  1. Send yourself through your own authorize URL, GET /oauth2/authorize, and sign in with the Google or Microsoft account that is listed as one of the application's developers.
  2. Approve the scopes on the consent screen, then exchange the code at POST /oauth2/token.
  3. Read records with the access token, for example POST /v1/operations/{type}/search: the token already says who the user is.

You see your own inbox's data and nobody else's: every call is checked against the signed-in user.

While only your developers have connected, the application stays APPROVED, and you can still change its redirect URIs. The first time anyone who is not one of your developers connects, the application becomes IMMUTABLE. From then on you can still change its redirect URIs on the hosts it already has (a new path or port, a new order, or removing one), and its description and links. A redirect URI on a new host needs bind.co's review, because users have already granted the application access: a direct edit is refused with 409 conflict and hint.reason new_redirect_host. To move to a new host, write to support@bind.co; bind.co reviews the change and applies it once approved. Scopes can be changed only while the application is a DRAFT.

Trying routes in the API reference

The API reference can call routes for you, signed in as one of your developers:

  1. Add https://api.bind.co/docs/oauth2-redirect to your application's redirect URIs. Do it while the application is still APPROVED: once it is IMMUTABLE, api.bind.co counts as a new host.
  2. In the reference, choose Authorize, enter your client_id and the scopes to try, and sign in. The reference uses PKCE.
  3. The code exchange needs your client_secret, so it is typed into the browser. Do this only on your own machine, never on a shared screen, and reset the secret in the developer portal if it may have been seen.

Calls made this way read and change your own records, like any other call your application makes.