Authorization

Search…
Overview
Authorization
Permissions
Authorization
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>.
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.
Header
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:
1
{
2
  "alg": "RS256",
3
  "kid": "e6:f7:d5:24:e2:59:06:2b:bc:a2:8c:35:9d:ca:0a:87",
4
  "typ": "JWT"
5
}
Copied!
Additional details related to signature verification can be found here.
Payload
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:
1
{
2
  "aud": "https://ident.provide.services/api/v1",
3
  "exp": 1599896478,
4
  "iat": 1599810078,
5
  "iss": "https://ident.provide.services",
6
  "jti": "54b84bdb-db5b-4c91-a9a1-e3d4abaf9dac",
7
  "nats": {
8
    "permissions": {
9
      "subscribe": {
10
        "allow": [
11
          "baseline.inbound",
12
          "user.2f18c7a7-5540-476c-a7a8-d5b30d2c90e6",
13
          "network.*.connector.*",
14
          "network.*.status",
15
          "platform.>"
16
        ]
17
      }
18
    }
19
  },
20
  "prvd": {
21
    "permissions": 536878465,
22
    "user_id": "2f18c7a7-5540-476c-a7a8-d5b30d2c90e6"
23
  },
24
  "sub": "user:2f18c7a7-5540-476c-a7a8-d5b30d2c90e6"
25
}
Copied!
Claims
The following claims are typically included in the signed token payload:
Claim
Field
Description
Audience
aud
the intended principal recipients who will process the token
Expiration
exp
the expiration time, expressed as a unix timestamp
Issued At
iat
the time the token was issued, expressed as a unix timestamp
Issuer
iss
the principal who issued and signed the token
Identifier
jti
unique identifier (UUID) for the token
NATS
nats
NATS application-specific claims, such as permissions
Not Before
nbf
optional time the token becomes valid, expressed as a unix timestamp
Provide
prvd
Provide application-specific claims, in the context of sub
Subject
sub
principal for which the token was vended
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:
1
-----BEGIN PUBLIC KEY-----
2
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0yqdJMBej1X8WwMMkMZw
3
DV6zZzup4RHLcln0xfGSm6dMPBDM1G96fuHhOwH5+uU5MQHJP7RqW71Bu5dLIG8Z
4
RX+XyUtb0sxCV/7X27Nm/bKpDysaSWQ36reAmw5wVaB1SoFeN519FY5rhoCWmH3W
5
auBAHTzpjg57p7uR0XynYXf8NSGXlysWHppkppqwrPH64G6UZaB7SMl1PFfkJeqZ
6
zJpzBGYWsixdF1EjXn+Yz0mhUZO2OSPWifOuN7cpn3BuNqegg4iVdz5HDoQhJW7N
7
uRhf3buKd/mjat8XA3e2Rkrr2h835GloScJkj7I4BZUNkzKQuEK6C9xW/zJtbPqQ
8
RYEq84A1hMfSZ3G5HFe2JkqiyvXkFwS3qMc5Pur8tZSzBj6AYMoJJso/aOdphpR8
9
6MaaWXWTwvwfpZbMRqehOcsmQcNLF2gLJPuHzR5WtVCnWrDgvjsWyeDD1WISKusi
10
aOeHxZjS3Bjl4Imq48l1wi2eI/11F/Xg70F4FJaMYLVHJA2nsmBuuQ9UDYHHq876
11
clKvIvgIItzJcv9lnmjl1Jks1DwCUF3qF2ugYcs9A3EoEcNzhMgZNJ2j5OUzfx1E
12
bzVKkqoC9MQpZWXgqV0KQqKK4I3rMY+1hLqk4S4eF9ZAVlT33qfMzlf0qWTOcP1Z
13
i2dsm0fy4NxWxknlEn5/LhMCAwEAAQ==
14
-----END PUBLIC KEY-----
Copied!
post
https://ident.provide.services
/api/v1/tokens
Authorize Token
post
https://ident.provide.services
/api/v1/authenticate
Authenticate User
get
https://ident.provide.services
/api/v1/tokens
List Revocable Tokens
delete
https://ident.provide.services
/api/v1/tokens/:id
Revoke Token