Authentication

Product APIs take an OAuth 2 access token as a bearer token. You get access tokens from the token endpoint with the refresh-token grant (RFC 6749 section 6). This page is the whole of it: the request, the response, every error, how long things last, and how to store what we give you.

The parts

• An integration is your software's identity. Its id, client_id in OAuth's terms, looks like int_example_a1b2c3d4. It is not a secret.
• A refresh token is the secret. It starts with sd_rt_ and is opaque to you. We issue one per integration, and only one is ever live.
• An access token is what you send with each call. It lasts 1 hour, acts for one brokerage only, and is opaque: never parse it.
• A grant is one brokerage's permission for your integration to act for it. Without a live grant, an access token for that brokerage is useless.
• A scope names something a token may do. A call needs the scope on the token and in the grant.

Backup developers

An integration has one owner: whoever created it in the developer portal. You can appoint colleagues as backup developers so the integration is not a single point of failure — from the integration's detail screen, add them by the email address they sign in to the portal with. They must already have signed in once: this never creates an account for them.

A backup developer can do everything the owner can — view and edit the integration, generate, rotate and revoke its refresh token, and see which brokerages have granted it access — except delete the integration or change who else is a backup developer. Those two stay the owner's own levers, so a brokerage's worth of colleagues can never lock the owner out of an integration they created.

Getting a grant

A refresh token lets your integration authenticate; it does nothing for a brokerage until that brokerage grants it access. There is no API call for this — a person at the brokerage decides it, on our consent screen, the same way Atlassian, Google and Microsoft ask.

Send the brokerage's user to:

https://suredocs.ie/authorize?client_id=YOUR_CLIENT_ID&broker_id=THEIR_BROKER_ID&scope=upload_file&state=YOUR_STATE&redirect_uri=YOUR_REDIRECT_URI

We reply by redirecting to your redirect_uri with two query parameters, state (yours, unchanged) and result (granted or denied). There is no code to exchange: the grant itself is the outcome, and the next call to the token endpoint (above) is how you find out it is live. A denied or abandoned request looks the same to you as one nobody ever opened — we do not tell you which.

/authorise (the Irish spelling) works identically, if you would rather use it.

Exchange a refresh token

POST https://api.suredocs.ie/oauth/token

Send a form (application/x-www-form-urlencoded, the standard) or JSON.

curl -sS https://api.suredocs.ie/oauth/token \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode client_id="$CLIENT_ID" \
  --data-urlencode refresh_token="$REFRESH_TOKEN" \
  --data-urlencode broker_id="$BROKER_ID"

The response is 200 with a JSON body:

{
  "access_token": "<the access token, a long opaque string>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<the NEXT refresh token>",
  "scope": "upload_file"
}

The response is never to be cached, and carries Cache-Control: no-store, because it holds credentials.

Every exchange returns a new refresh token

Each successful exchange returns a new refresh token beside the access token, and the one you presented stops working (RFC 9700 section 4.14.2). A refresh token that is presented after it has been used is treated as stolen: we cannot tell which of two holders is the thief, so we revoke the integration's live refresh token, and it has to be reissued by us. Ordinary OAuth libraries already handle a new refresh token in a response. These rules are what your code has to add:

• Store the new refresh token durably before you use the access token that came with it. A process that dies between receiving a response and storing its refresh token has lost the token, and the grace period below is the only recovery.
• Exchange from one place at a time. One refresh token covers every brokerage your integration acts for, so exchanges for different brokerages must be serialised too, not only exchanges for the same one. Two servers refreshing independently looks exactly like theft and revokes the token.
• On a timeout or a lost response, retry with the same refresh token within 10 minutes. Never retry with an older one. The retry issues a fresh successor, and the response you lost is not repeated.
• Do not loop on invalid_grant. It does not fix itself. Contact us.
• Exchange when the access token is about to expire, not before every call. An access token is good for 1 hour.

How long things last

When we revoke a refresh token or suspend an integration, the token endpoint refuses you at once. Access tokens already issued keep working until they expire, which is at most 1 hour, apart from a suspension or a revoked grant, which are refused within about a minute.

Calling an API

Send the access token in the Authorization header, and nowhere else:

Authorization: Bearer <access token>

A token in a query string or a request body is treated as no token at all. Never send a token over plain HTTP.

Scopes

The scopes are a closed list, and no scope implies another.

Errors from the token endpoint

The token endpoint answers errors in the shape RFC 6749 section 5.2 gives, because that is what OAuth libraries parse. This is different from the product APIs' error shape below.

{
  "error": "invalid_grant",
  "error_description": "The refresh token cannot be used."
}

Branch on error and the HTTP status. error_description is for a person, may be reworded at any time, and must never be matched.

Errors from a product API

A product API answers every error with one shape:

{
  "status": 403,
  "reason": "insufficient_scope",
  "message": "This token does not carry the upload_file scope.",
  "requestId": "2f4a5f8e-9d3c-4b6e-8f4a-0c5b1e7d2a90"
}

reason is what your code branches on. message is for a person and is never matched. requestId is the Request-Id header again: quote it when you report a problem.

Operations also have their own reasons, listed in the API reference.

Do not retry a 401 in a loop

A 401 is not a reason to send the same request again. It means the access token is not usable, so nothing changes until you have a different one. The right response is one exchange for a new access token, and one repeat of the call. If the repeat is a 401 as well, something else is wrong: stop, and report the Request-Id of the failing call. A loop that exchanges on every 401 will exhaust the token endpoint's rate limits, and a loop that sends several exchanges at once looks like theft and revokes your refresh token.

Storing a refresh token safely

A refresh token is a credential for every brokerage that has granted your integration access. Treat it as you would a database password.

• Keep it in a secret store or an encrypted parameter, and never in source control, a container image, a ticket or a chat message.
• Never write it to a log, an error report or a URL. The sd_rt_ prefix is there so that a leaked token can be found by a secret scanner; make sure one is looking.
• Give it to as few processes as you can. Exactly one of them exchanges it, holding a lock, so that two exchanges are never in flight.
• Write the new token to the store before you use the access token that arrived with it, and make the write atomic, so a crash leaves you with the old token or the new one and never neither.
• If you think it has leaked, tell us at once at support@suredocs.ie. We revoke it and issue a new one. Access tokens already minted from it live out their 1 hour.