Access Keys

Access keys replace the existing API keys and provide fine grained permissioning to the bearer. They can be used interachably with API keys, which will eventually be deprecated.

Scopes

scopes is a map-like structure that enumerate the capabilities granted to the key's user. Each key of scopes corresponds to a resource which may vary in the granularity of access control. Currently, the supported scopes are:

access_keys, audit_events, and decision are specified exactly like

{
  "scopes": {
    "customer": {
      "decision": true, 
      "audit_events": true,
      "access_keys": ["policies","sets"]
    }
  }
}

However, policies and sets have additional access control options that are enumerated using the list value, which has at most 10 elements. Each list element consists of a map-like structure like

{
  "f": "*",
  "p": 7
}

where "f" is a selector for a set of resources and "p" is an integer representing the union of permissions.

Selector

A selector is a simple pattern for identify the set of resources.

  • A "*" selector describes any or all resources.
  • A "exact" selector describes a single resource named "exact".
  • A "prefix*" describes any or all resources whose name or identifer starts with "prefix".

Permissions

A standalone permission is one of the following

Description Value Supported Selectors
Create 1 "*"
Read* 2 "*", "exact", or "prefix*"
Update 4 "*", "exact", or "prefix*"
Delete 8 "*"

*Create, Update, or Delete also implies Read permission.

Standalone permissions can be combined, so a "p" value of 7 equals to Create | Read | Update.

Example

{
  "scopes": {
    "customer": {
      "decision": true,
      "access_keys": ["*"],
      "policies": [
        {
          "f": "*",
          "p": 2
        },
        {
          "f": "staging",
          "p": 4
        }
      ]
    }
  }
}

This access key is permitted to:

  • Call any /decision endpoint,
  • Call any /v1/access_keys endpoint,
  • Call any /v1/auditing endpoint,
  • Call the GET /v1/policies or GET /v1/policies/{policyname} endpoints, or
  • Call the PUT /v1/policies/staging endpoint.

API

Limits

  • A customer can have up to 10 active keys.
    • A key is active if it is unexpired and unrevoked.

POST /v1/access_keys

Request

{
  // required
  "scopes": {
    "customer": {
      "decision": []
    }
  },
  // optional RFC3339 (https://tools.ietf.org/html/rfc3339) timestamp string
  "expires_at": "2022-12-31T23:59:59Z"
}

Response (Status Code: 201)

{
  "id": "9017501f-9fa4-4a88-b657-5bd49c1bb722",
  "customer_id": "123456",
  // use the key for interacting with the API's
  "key": "...",
  "scopes": {
    "customer": {
      "decision": true
    }
  },
  "expires_at": "2022-12-31T23:59:59Z",
  "created_at": "2021-12-31T23:59:59Z",
  "revoked_at": null
}

DELETE /v1/access_keys/{id}

This endpoint revokes a currently active access key.

Request

This endpoint has no request body.

Response (Status Code: 200)

{
  "id": "9017501f-9fa4-4a88-b657-5bd49c1bb722",
  "customer_id": "123456",
  "scopes": {
    "customer": {
      "decision": true
    }
  },
  "expires_at": "2022-12-31T23:59:59Z",
  "created_at": "2021-12-31T23:59:59Z",
  "revoked_at": "2022-01-31T23:59:59Z"
}

GET /v1/access_keys

Request

This endpoint has no request body.

Response (Status Code: 200)

{
  "access_keys": [
    {
      "id": "9017501f-9fa4-4a88-b657-5bd49c1bb722",
      "customer_id": "123456",
      "scopes": {
        "customer": {
          "decision": true
        }
      },
      "expires_at": "2022-12-31T23:59:59Z",
      "created_at": "2021-12-31T23:59:59Z",
      "revoked_at": null
    },
    {
      "id": "c99cf497-4b26-4490-94cf-d5d748f35f9f",
      "customer_id": "123456",
      "scopes": {
        "customer": {
          "policies": [
            {
              "f": "*",
              "p": 2
            }
          ]
        }
      },
      "expires_at": "2022-12-31T23:59:59Z",
      "created_at": "2021-12-31T23:59:59Z",
      "revoked_at": null
    }
    ...
  ]
}

GET /v1/access_keys/{id}

Request

This endpoint has no request body.

Response (Status Code: 200)

{
  "id": "9017501f-9fa4-4a88-b657-5bd49c1bb722",
  "customer_id": "123456",
  "scopes": {
    "customer": {
      "decision": true
    }
  },
  "expires_at": "2022-12-31T23:59:59Z",
  "created_at": "2021-12-31T23:59:59Z",
  "revoked_at": null
}