Scoped Access Tokens¶

The Groups API documentation specifies the syntax and meaning of policy definitions. Reviewing that documentation will be helpful before using Scoped Access Tokens.

Scoped Access Tokens are a special type of authentication principal in TrueVault that allows limited access to specific resources. Scoped Access Tokens can have custom expiration times and can have limited number of uses (e.g. single use tokens).

Scoped Access Tokens are ideal for access that must be authenticated but cannot be performed by an authenticated user.

For Example:

A forgot password flow requires authentication to update a users password, but the user cannot authenticate if they have forgotten their password, so a single-use SAT can be used instead.

Public registration may be allowed for your application, but user creation always requires authentication in TrueVault. Using an SAT you can allow user registration from a public page without creating a system user for that purpose.

Composition¶

Scoped Access Tokens are composed of a secret component and an identifier. These are serialized by the API in a JSON object called http_auth that looks like:

http_auth: {
    "password": "<the secret component>",
    "username": "<the identifier>"
}

When providing an SAT as authentication for an API request, you should provide the username and password as HTTP Basic Auth values. Specifically, concatenate the two, separated by a colon (username:password) then base64 the result. Pass this in the HTTP Authorization header. You can read more about HTTP Basic Auth here.

Create a Scoped Access Token¶

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png

POST /v1/scoped_access_tokens¶

Create a new scoped access token.

Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN` or `SCOPED_ACCESS_TOKEN` Content-Type – `application/json`
Request JSON Object:
	name(req’d) (string) – the name for this SAT (100 characters or fewer) policy(req’d) (object) – The policy for this SAT. See https://docs.truevault.com/groups#groups-api for policy definition documentation. not_valid_after(req’d) (string) – expiration time of the return SAT (ISO 8601 format in zulu timezone) allowed_uses(req’d) (int) – the maximum number of times this SAT can be used

Example Request

curl https://api.truevault.com/v1/scoped_access_tokens \
    -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN | SCOPED_ACCESSS_TOKEN]: \
    -d '{
         "name": "Reset Password Token 123",
         "policy": [{"Resources": ["User::00000000-0000-0000-0000-000000000000::Password"], "Activities": "U"}],
         "not_valid_after": "2028-08-14T22:38:06.156304Z",
         "allowed_uses": 10
    }'

Example Success Response

The response contains the relevant data for the newly created SAT including the authentication information.

{
    "scoped_access_token": {
        "allowed_uses": 10,
        "consumed_uses": 0,
        "http_auth": {
            "password": "...",
            "username": "sat-..."
        },
        "id": "...",
        "name": "Reset Password Token 123",
        "not_valid_after": "2028-08-14T22:38:06.156000Z",
        "policy": [{"Activities": "U", "Resources": ["User::00000000-0000-0000-0000-000000000000::Password"]}]
    },
    "result": "success",
    "transaction_id": "58b30515-9398-428d-8280-9f6e43488229"
}

Delete a Scoped Access Token¶

DELETE /v1/scoped_access_tokens/(string: token_id)¶

Deletes a scoped access token.

Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN` or `SCOPED_ACCESS_TOKEN` Content-Type – `application/json`
Parameters:	token_id – string(req’d) supplied as a URL path parameter.

Example Request

curl https://api.truevault.com/v1/scoped_access_tokens/00000000-0000-0000-0000-000000000000 \
    -X DELETE \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN | SCOPED_ACCESSS_TOKEN]: \

Example Success Response

The response indicates success and provides a transaction_id.

{
    "result": "success",
    "transaction_id": "685f0f81-9b18-45a5-9205-fa35c1d3970a"
}

List Scoped Access Tokens¶

GET /v1/scoped_access_tokens¶

Lists all scoped access tokens.

Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN` or `SCOPED_ACCESS_TOKEN` Content-Type – `application/json`

Example Request

curl https://api.truevault.com/v1/scoped_access_tokens/ \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN | SCOPED_ACCESSS_TOKEN]: \

Example Success Response

The response provides all SATs.

{
   "data": {
     "items": [
       {
         "allowed_uses": null,
         "consumed_uses": 0,
         "id": "...",
         "name": "Password Reset Flow 123",
         "not_valid_after": "3000-02-01T08:00:00Z",
         "policy": [
           {
             "Activities": "C",
             "Resources": [
               "PasswordResetFlow::00000000-0000-0000-0000-00000000000::Email::.*"
             ]
           }
         ]
       }
     ]
   },
   "result": "success",
   "transaction_id": "d153b7d8-bfa9-4a6f-813c-088a919295f9"
 }

Get a Scoped Access Token¶

GET /v1/scoped_access_tokens/(string: token_id)¶

Gets a scoped access token.

Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN` or `SCOPED_ACCESS_TOKEN` Content-Type – `application/json`
Parameters:	token_id – string(req’d) supplied as a URL path parameter.

Example Request

curl https://api.truevault.com/v1/scoped_access_tokens/00000000-0000-0000-0000-000000000000 \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN | SCOPED_ACCESSS_TOKEN]: \

Example Success Response

The response indicates success and provides a transaction_id.