Authorization Service

The Authorization Service enables callers to generate service access tokens. A service access token is similar to a tenant-level security access key, in the sense that it provides access to one or more SBS services to a given tenant, for a given application. Like service access keys, service access tokens have a scope that defines which services (or even which queries and mutations within a service) are available to the bearer of the token.

Unlike service access keys, service access tokens expire, and thus are more suitable for use on the client side of your application. You can specify the token’s scope and expiry period when generating the token.

There is one more important difference between service access keys and service access tokens. To generate the former, you need access either to the SBS Console or to the Account API. To generate a service access token, however, you need a service access key whose scope allows access to the Authorization Service.

A service access token stops being valid once it expires. Before then, the holder of a token can also revoke it — see How to revoke a service access token. Revoking a token ends only that token. To block a tenant’s access to a service across every credential the tenant holds, generate a Service Access Denial instead.

A service access token provides the same level of access like a tenant-level security access key. Therefore, it cannot be used to access services that accept an application-level security access key only (for example, User Management Service). If a service accepts both a tenant-level or application-level security access key, then you can access it with a security access token.

Access info

How to use service access tokens

With a service access token, you can access SBS resources by populating the Authorization header of the HTTP(S) request as follows:

{"Authorization": "Bearer some-service-access-token"}

Where the value after “Bearer” is a service access token generated through the Authorization service.

How to revoke a service access token

When a token has served its purpose, or you suspect it has been exposed, you can revoke it before it expires. Send an HTTP POST request to the revocation endpoint, presenting the token you want to revoke in the Authorization header:

POST https://authorization-api.socrate.io/remove-service-access-token
Authorization: Bearer YOUR_SERVICE_ACCESS_TOKEN

The request needs no body, and any body you send is ignored. The endpoint revokes only the token you present, and only the holder of a token can revoke it: the request accepts no other credential and no value that names a different token. You can revoke a token whatever its scope; the token does not need to be scoped to the Authorization Service.

The endpoint refuses any request that does not present a valid, unexpired token. This includes a request with no Authorization header, a header that is not of the form Bearer <token>, a token the platform does not recognize, and a token that has expired. Every such refusal is identical, so it does not reveal why the request was refused. Revoking a token that has already been revoked is refused rather than confirmed; a sign-out routine should treat this refusal as normal, not as an error.

If a revocation request does not succeed, the token is still usable. Retry the request with the same token.

Queries

version

Returns the API version.

Mutations

generateServiceAccessToken

Generates a service access token.

Arguments

GenerateServiceAccessTokenInput input

Result

ServiceAccessToken type

Example

The following call generates a service access token that grants access to all queries and mutations of the Email Service and File Management Service. The token is set to expire in 1 day (86400 seconds).

mutation generateToken($input:ServiceAccessTokenInput!) {
  generateServiceAccessToken(input:$input) {
    id
    accessToken
    expiresIn
    scope
    createdAt
  }
}

{
  "input": {
    "expiresIn": 86400,
    "scope": "email-api:query:* email-api:mutation:* file-management-api:query:* file-management-api:mutation:*"
  }
}

Error codes

See Conventions for the error format and the codes shared across all services. This service can also return the following codes: