Skip to main content
The v3 data endpoint is authenticated with a bearer token that is scoped to a single store. Tokens belong to a service account, a non-human user of your store with its own scopes.

Service accounts

To create a service account:
  1. Log in to your Redo Dashboard
  2. Go to Settings → Developer
  3. In Service accounts, click Create service account, then name it and choose its scopes
A service account authenticates with one or more credentials. To add one, open the account’s Credentials and click Add in one of its sections: Every credential has its service account’s scopes. Changing the account’s scopes changes what all of its credentials can do.

Store ID

Your Store ID is part of the data endpoint path. It is shown in the General section of Settings → Developer in the Redo Dashboard.

API keys

Add an API key and copy it from the confirmation dialog. It starts with redo_sk_.
Store your API key securely. It is only shown once, when created. Never share it publicly or commit it to version control.
Send every operation as a POST to the data endpoint for your store, with the key in the Authorization header:
The token is checked against the store in the path. A malformed header, an unknown token, and a token that belongs to a different store all fail the same way, with HTTP 401 and an Unauthorized error, so they cannot be told apart:

Access tokens

Public keys and federated policies don’t send a secret to the API. Instead, you exchange a signed JWT for a one-hour access token at Redo’s token endpoint, and send the access token as the bearer token, the same way as an API key.
The endpoint follows OAuth 2.0. Its metadata is at https://auth.redo.com/.well-known/oauth-authorization-server, so most OAuth client libraries can configure themselves from it. A successful response looks like:
Request a new token before expires_in runs out. To get a token with fewer scopes than the service account has, send a space-separated scope parameter.

Public keys

Add your public key as a JWK (for example, the public half of an RSA or EC key pair). Redo shows its Fingerprint, the key’s RFC 7638 SHA-256 thumbprint. Request a token with the client credentials grant, authenticating with a JWT signed by your private key (RFC 7523):
The assertion JWT needs:
  • kid header: the key’s fingerprint
  • iss and sub: the service account’s Client ID, shown in its Credentials and as clientId in the API
  • aud: https://auth.redo.com
  • exp: a short expiry, such as five minutes

Federated policies

A federated policy trusts tokens from an OpenID Connect issuer, so a platform that already issues them needs no Redo secret at all. Add a policy with:
  • Issuer: the issuer URL, such as https://issuer.example.com. Redo reads its signing keys from its OpenID Connect discovery document, so it must be public.
  • Claim conditions: the token must match every condition. A claim is a JSON Pointer into the token, such as /sub or /email. In a pattern, * matches any characters and \* matches a literal *, so *@example.com matches any address at example.com. A /sub pattern must name the subject before any *, such as https://service16.example.com/*, so a policy can’t trust every subject an issuer signs.
Configure the issuer to set the token’s audience to your store’s data endpoint URL, https://api.getredo.com/v3/account/{storeId}, as its only audience. The token must also have iat and exp, and live for at most an hour. Then exchange it for an access token (RFC 8693):
Every refusal returns the same invalid_grant error, whether the issuer is unknown, the signature is wrong, or no policy matches. A token that matches policies on more than one service account is also refused.

Scopes

Service accounts carry scopes that determine which fields their tokens may read or write. Because a nested field’s scope adds to its parent’s, a request needs the union of every scope along its selection paths. A request that selects any field its token is not scoped for is rejected before it runs, with HTTP 403 and the error code INSUFFICIENT_SCOPE. Under a field that returns an interface or union, such as node(id:), a fragment on one type (... on Product { ... }) needs its scopes only when the returned object is that type. If the token lacks one, that field is null with the same error, and the rest of the response is still returned. Choose a service account’s scopes in Settings → Developer, and grant only the scopes it needs. See Access scopes for the full list, and the Required scopes on each query, mutation, and field in the reference. A caller can only give a service account scopes it holds itself. To manage service accounts through the API, a token needs user_read or user_write, and it can’t change, delete, or add credentials to a service account that has scopes the token lacks.

Introspection without a token

The schema endpoint (https://api.getredo.com/v3/graphql-schema) is unauthenticated and exposes the schema only, never store data. Use it to explore types and generate clients without a token.