Authorize with the Provide stack

Bearer Authorization

Provide requires the presence of a bearer API token to authorize most API calls. A bearer API token is an encoded JWT which contains a subject claim (sub) which references an authorized entity (i.e., the User, Application or Organization). The authorized entity uses a signed bearer authorization Token to access one or more resources for which the Token was authorized. Unless otherwise noted, all API requests must include a header such as Authorization: bearer <jwt>.

Authentication/Authorization JWT's for users, organizations and applications/workgroups can be obtained through the Provide-CLI or through Ident API.

Access/Refresh Tokens

In accordance with the OAuth 2.0 specification, when an entity is authorized and the requested scope includes offline_access, a refresh token is vended and returned on behalf of the caller. This refresh token is long-lived and can be used to authorize short-lived access tokens using the refresh_token grant type on subsequent authorization requests.

This pattern is useful for machine-to-machine applications; a secure practice is to store the long-lived refresh token in a Vault instance (i.e., as a secret), read it into application memory during container initialization and then use it to authorize a short-lived access token. If the container remains running long enough for the access token to expire, the refresh token should once again be used to seamlessly authorize a new access token.

Encoded JWT

The standard and application-specific bearer claims are encoded as JWT and signed using the RS256 (RSA Signature with SHA-256) or Ed25519 (Edwards-curve Digital Signature) algorithm.


When verifying a JWT, the algorithm used for signing and an identifier referencing the public key to use for signature verification can be found in the alg and kid headers, respectively:

  "alg": "RS256",
  "kid": "e6:f7:d5:24:e2:59:06:2b:bc:a2:8c:35:9d:ca:0a:87",
  "typ": "JWT"

Additional details related to signature verification can be found here.


The encoded JWT will, in most cases, include an expiration timestamp (exp) after which the token is no longer valid. A Token issued without an expiration date (i.e., certain machine-to-machine API tokens) must be explicitly revoked.

The following payload illustrates how standard and application-specific claims are encoded in a bearer JWT:

  "aud": "",
  "exp": 1599896478,
  "iat": 1599810078,
  "iss": "",
  "jti": "54b84bdb-db5b-4c91-a9a1-e3d4abaf9dac",
  "nats": {
    "permissions": {
      "subscribe": {
        "allow": [
  "prvd": {
    "permissions": 536878465,
    "user_id": "2f18c7a7-5540-476c-a7a8-d5b30d2c90e6"
  "sub": "user:2f18c7a7-5540-476c-a7a8-d5b30d2c90e6"


The following claims are typically included in the signed token payload:

Signature Verification

The encoded JWT is signed using the the RS256 (RSA Signature with SHA-256) or Ed25519 (Edwards-curve Digital Signature) algorithm. The following public key can be used to verify the signature:

-----END PUBLIC KEY-----

Last updated