Access Keys

An Access Key is a token that allows the bearer to interact with the “Policy Management“ section of the dashboard. This section enables users to perform Create, Read, Update and Delete (CRUD)operations on policies, sets and Access keys depending on the type of the user (i.e. user, Admin, InternalAdmin). Access keys provide fine-grained permissions to the bearer.

Access Keys Creation Process

User’s access keys can be created and assigned in two different ways:

  • By default when creating a new dashboard user.
  • Through the “Policy Management“ section in the dashboard.

Creating and Assigning an Access Key by Default

The process of creating mitigation API access keys for new users is part of the user-creation flow. Every time a new user is created, an access key will be automatically generated and assigned to the user’s profile.

The key permissions will be determined by the user type selected from the dropdown.

user-creation-screenshot

Viewing Access Keys

Access keys can viewed be in the "Policy Management" section of the dashboard.

key-mgmt-screenshot

Clicking on a key allows one to view the detailed scope granted by each key.

key-detail-screenshot

Scopes

Each Key Scope is a map-like structure that enumerates 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 like so:

{
  "scopes": {
    "customer": {
      "decision": true,
      "audit_events": true,
      "access_keys": [
        "access_keys",
        "audit_events",
        "decision",
        "policies",
        "sets"
      ]
    },
    "metadata": {
      "username": "dale.cooper",
      "keyname": "dale.cooper"
    }
  }
}

access_keys can receive any supported scope. The above request is setting the complete list of supported scopes but in this case, we can replace it with "*" as shown below.

  • The scope access_keys won't allow an access_key to create other access_keys. This may be supported in future. 
{
  "scopes": {
    "customer": {
      "decision": true,
      "audit_events": true,
      "access_keys": ["*"]
    },
    "metadata": {
      "username": "dale.cooper",
      "keyname": "dale.cooper"
    }
  }
}

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

{
  "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 identifying a 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 identifier 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 "*", "exact", or "prefix*"

*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
        }
      ]
    },
    "metadata": {
      "username": "dale.cooper",
      "keyname": "dashboard_dale.cooper"
    }
  }
}
  • Your Customer Success representative will provide you with a starter key and can help you obtain keys with more advanced features to give you full control of your account.

This access key is permitted to:

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

Set Granularity

On top of permission scopes, sets offer granularity over the format of a set type and its values. This allows a key to have permissions to interact with sets as with policies. An administrator can restrict the values that a key is allowed to update for a set.

For instance, in the following example the key's scope allows the key to update a set as long as the set is of entity type string and follows the regex pattern provided:

{
  "scopes": {
    "customer": {
      "decision": true,
      "access_keys": [
        "*"
      ],
      "sets": [
        {
          "f": "*",
          "p": 15,
          "r": {
            "entity_type": "^string$",
            "filter": "^[A-Z]+\\.[A-Z]+$"
          }
        }
      ]
    }
  }
}

Example filters

  • restrict if of type string and make sure the value is of the format CAPITALS.CAPITALS
{
  "entity_type": "^string$",
  "filter": "^[A-Z]+\\.[A-Z]+$"
}
  • restrict if of type string and make sure the value is of the format 3 capitals followed by a dash and then up to 3 capitals (e.g. ABC-A, or ABC-AB, or ABC-ABC)
{
  "entity_type": "^string$",
  "filter": "^[A-Z]{3}-[A-Z]{1,3}$"
}
  • restrict if of type ip and as long as the IP address starts in the range 0-135 (note invalid IP addresses will return a BAD request anyway, e.g. 999.999.999.999)
{
  "entity_type": "^ip$",
  "filter": "^[0-1][0-3][0-5]\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}$"
}

It is up to the filter regex to be valid within its context, e.g. an entity_type of uint could be restricted by a filter of ^[A-Z]{1,5}$ but it is meaningless in this context and would cause all values to be blocked.

Metadata

This is a map-like structure where you can define your own fields. This is useful to identify keys per username, keyname or any other field you may define e.g. "environment":"staging".

  • The fields username and keyname in metadata are mandatory in order to identify who the key belongs to.

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": true
    }
  },
  "metadata": {
    "username": "dale.cooper",
    "keyname": "dale.cooper"
  },
  // 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
    }
  },
  "metadata": {
    "username": "dale.cooper",
    "keyname": "dale.cooper"
  },
  "expires_at": "2022-12-31T23:59:59Z",
  "created_at": "2021-12-31T23:59:59Z",
  "revoked_at": null
}

Other possible response scenarios:

  • Bad Request (Status Code: 400)
  • Unauthorized (Status Code: 401)
  • Forbidden (Status Code: 403)
  • Too many keys created (Status Code : 500)
  • Internal server error (Status Code: 500)
  • Invalid scope values for access_keys field (Status Code: 400)
  • Missing mandatory metadata fields (Status Code: 400)
  • Invalid values for permissions "p" or selector "f" in policies or set (Status Code: 400)

DELETE /v1/access_keys/{id}

This endpoint revokes a currently active access key.

Request

This endpoint has no request body.

Response (Status Code: 204)

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

Other possible response scenarios:

  • Unauthorized (Status Code: 401)
  • Already revoked key (Status Code: 409)
  • Internal server error (Status Code: 500)
  • No record with that ID was found (Status Code: 404)

GET /v1/access_keys

This endpoint returns access keys.

Request

This endpoint has no request body.

Optional Query Parameters

GET /v1/access_keys?status={all|revocked}&limit=10&offset=0&sort_field={created_at|revoked_at}&sort_direction={asc|desc}&metadata.username=USERNAME

Parameter Default Value
status returns the active keys for default
limit 10
offset 0
sort_field created_at
sort_direction desc
metadata.username returns all the keys associated with the provided username. All keys will be returned by default.

Response (Status Code: 200)

{
  "limit": 10,
  "offset": 0,
  "total": 5,
  "access_keys": [
    {
      "id": "9017501f-9fa4-4a88-b657-5bd49c1bb722",
      "customer_id": "123456",
      "scopes": {
        "customer": {
          "decision": true
        }
      },
      "metadata": {
        "username": "dale.cooper",
        "keyname": "dale.cooper"
      },
      "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
            }
          ]
        }
      },
      "metadata": {
        "username": "dale.cooper",
        "keyname": "dale.cooper"
      },
      "expires_at": "2022-12-31T23:59:59Z",
      "created_at": "2021-12-31T23:59:59Z",
      "revoked_at": null
    },
    ...
  ]
}

Other possible response scenarios:

  • Unauthorized (Status Code: 401)
  • Internal server error (Status Code: 500)

GET /v1/access_keys/{id}

This endpoint returns the specified access keys.

Request

This endpoint has no request body.

Response (Status Code: 200)

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

Other possible response scenarios:

  • Unauthorized (Status Code: 401)
  • Internal server error (Status Code: 500)
  • No record with that ID was found (Status Code: 404)

Considerations:

  • Any access_keys that don't have an expires_at field will be always valid until they are revoked.

Dashboard Usage:

Some access_keys will have a keyname like "dashboard_xxxx", this is to identify the keys that are meant to be used in the dashboard. This prefix is added automatically by the dashboard when creating an access_key.