Introduction

Scheduled key rotation is a security best-practice. Having a process in place for regularly rotating your Pinwheel API keys has the following benefits:

• In the event of a discovered data breach, keys should be rotated immediately. If you already have a process in place, this can be accomplished quickly and with little effort.
• If a key is breached but this goes undiscovered, scheduled rotation ensures that the impact from an undiscovered breach is short-lived.

Pinwheel's key rotation capability allows you to easily rotate your API keys without any risk of downtime. This is accomplished by creating multiple active keys and ensuring your apps are using the new key before revoking the old key.

❗️

Keep your secrets a secret

Make sure to keep your API secrets secure! You should avoid storing or using API secrets in client-side code, GitHub, or other non-secure spots.

Pinwheel API Key Rotation Procedure

At a high level, the procedure for rotating your Pinwheel API keys without any downtime looks like this:

1. Create a new API key using either the Dashboard or programmatically with the Admin API.
2. Update your secret store with the new key and secret.
3. Ensure your apps are all using the new key’s secret.
4. Revoke the previous token, using either the Dashboard or Admin API.

Enhanced Security

At Pinwheel, we take security extremely seriously. To that end, we offer two additional security features around API Key management:

• Your API key’s secret is available immediately after creation, but after that, it is no longer accessible. As a result, you should copy or download the new secret immediately after creating your keys.
• Keys can now be created with an optional expiration date.

Note: For convenience, Sandbox key secrets will remain visible even after key creation, as Sandbox data is fake and does not need to be protected.

User permissions

The ability to rotate keys depends on your workspace user’s role. The roles and their associated permissions are outlined here:

1. Owner - the user that owns the workspace. The owner can invite new users to their workspace and designate whether that user will be an administrator or a developer. Owners can view, create and revoke keys.
2. Administrator - these users can view, create and revoke keys.
3. Developer - these users can view keys but do not have the ability to create or revoke keys.

Key Rotation using Dashboard

Creating Keys

1. Log in to your Dashboard account. Navigate to API Keys, select Create New Key
2. You can set the key to automatically expire by entering a date, or leave empty if you do not want the key to automatically expire

3. Select Create New Key to generate the new API Key and Secret
4. Once the new key is created you must copy or download the secret; the secret will not be shown again after the initial creation

5. An email will be sent to the workspace owner when a key is created, from the email address [email protected]. Please whitelist this email address to reduce the the chance these notifications get caught in spam filters.

Note: There is a limit of ten active keys. Attempting to create a key after this limit has been reached will result in an error.

Revoking Keys

1. Log in to your Dashboard account. Navigate to API Keys
2. Select Revoke Key
3. Confirm you would like to Revoke Key, this action is immediate and irreversible.

4. An email will be sent to the workspace owner when a key is revoked, from the email address [email protected]. Please whitelist this email address to reduce the the chance these notifications get caught in spam filters.

Note: There are no restrictions on revoking your only active key. Care should be taken to ensure that at least one API key remains active, otherwise your app(s) will lose access to the Pinwheel API.

Key Rotation using Admin API

Authentication

Access to the Admin API is authenticated using Dashboard user credentials. You will pass the credentials to the authentication endpoint and in return receive a token that will be valid for 5 minutes if credentials are authenticated successfully. This short-lived token is used to authorize access to the query, create, and revoke endpoints listed below.

The server name used to authenticate determines the mode for the subsequent endpoint calls. In other words, authenticating with the sandbox URL will ensure that only sandbox keys can be queried, created, and revoked.

Note: The Dashboard used to access the Admin API must be associated to a single workspace. If, for example, you’ve created two workspaces for two environments, and the Dashboard user you’re using for Admin API has access to both workspaces, then authentication will fail.

Endpoint: POST <server name>/v1/admin/token

Request body:

{
	"username": "<dev dashboard username>",
	"password": "<dev dashboard password>"
}

Successful response body:

{
	"data": {
		"token": <token:string>,
		"expiration": <expires_at:timestamp>,
		"workspace_name": <workspace:string>,
		"mode": <mode:"sandbox"|"development"|"production">,
		"user_role": <role:"owner"|"administrator"|"developer">
	}
}

Error responses are returned for invalid credentials (401 INVALID_CREDENTIALS), or if the user is associated with multiple workspaces (400 BAD_REQUEST)

Querying Keys

You can call this endpoint to receive a list of all active and inactive keys for your workspace. Only the public key part will be returned, as the secret is only available upon creation. All user roles are able to access this endpoint.

This is a paginated endpoint (see pagination docs for more). If no limit is specified the default page size will be 25 entries.

Endpoint: GET /v1/admin/api_keys?limit=<page size>&cursor=<cursor>

Request headers:

Authorization: Bearer {token}

The token is returned in the response of the authentication endpoint described above.

Successful response body:

{
	"meta": {
    "count": <limit>,
    "next_cursor": "<cursor>"
  },
	"data": [
		{
			"mode": "sandbox|development|production",
			"key": "<key>",
			"expires_at": "<expires_at>"|null,
			"is_active": <true|false>,
			"last_used_at": "<date>"|null,
			"created_at": "<created_at>",
			"revoked_at": "<revoked_at>"|null
		},
		...
	]
}

Error responses are returned for invalid token (401 UNAUTHORIZED), or if access to a mode has not been granted (401 UNAUTHORIZED).

Creating Keys

This endpoint will allow owners and administrators to create new API keys. The response contains both the public key and the private secret. Secrets are only viewable upon creation, so care should be taken to store the secret as part of creating the key.

When a key is created an email is sent to the workspace owner, from the email address [email protected]. Please whitelist this email address to reduce the the chance these notifications get caught in spam filters.

Note: There is a limit of ten active keys. Attempting to create a key after this limit has been reached will result in an error.

Endpoint POST /v1/admin/api_keys

Request headers:

Authorization: Bearer {token}

The token is returned in the response of the authentication endpoint described above.

Request body (optional):

{
	"expires_at": "<timestamp>"
}

Successful response body

{
	"data": {
		"mode": "sandbox|development|production",
		"key": "<key>",
		"secret": "<secret>",
		"expires_at": "<expires_at>" | null,
		"created_at": "<created_at>",
	}
}

Error response are returned for invalid token (401 UNAUTHORIZED), if access to a mode has not been granted (401 UNAUTHORIZED), if the user has the developer role (403 Forbidden), or if there are already the maximum number of active keys (429 Too Many Requests).

Revoking Keys

This endpoint will allow owners and administrators to revoke an existing key. This action is immediate and irreversible. Unlike with the Dashboard, there is no confirmation step, so take care to ensure this is the desired action.

When a key is revoked an email will be sent to the workspace owner confirming the details, from the email address [email protected]. Please whitelist this email address to reduce the the chance these notifications get caught in spam filters.

Note: There are no restrictions on revoking your only active key. Care should be taken to ensure that at least one API key remains active, otherwise your app(s) will lose access to the Pinwheel API.

Endpoint: POST /v1/admin/api_keys/{api_key}/revoke

Request headers:

Authorization: Bearer {token}

The token is returned in the response of the authentication endpoint described above.

Successful response body:

{
	"data": {
		"mode": "sandbox|development|production",
		"key": "<key>",
		"created_at": "<created_at>",
		"revoked_at": "<revoked_at>",
	}
}

Error response are returned for invalid token (401 UNAUTHORIZED), if access to a mode has not been granted (401 UNAUTHORIZED), or if the user has the developer role (403 Forbidden).