API Authentication Guide

Introduction

This document will walk you through the steps to authenticate your API requests using a combination of an admin key and API keys.

Key Concepts

Admin Key: The key provided to the admin user for managing API keys and users.
API Key: Keys created by the admin user for general API usage.

Getting Started

1. Using the Admin Key

To get started with API authentication, you must first create API keys with your Admin Key. If you're a SaaS customer, the admin key will be provided to you via a secure secret share mechanism. If you're an on-prem customer, you can find the admin key in the platform's secrets manager.

To use the admin key, include it in the request header of your API requests under the Authorization field as a Bearer token.

Example:

GET /auth/api_keys
Authorization: Bearer YourAdminKey

2. Creating API Keys

To create an API key, make a POST request to the API endpoint, /auth/api_keys with the Admin Key in the request header. Please refer to the permissions <> roles matrix for the available roles.

Example:

POST /auth/api_keys
Authorization: Bearer YourAdminKeyHere
Content-Type: application/json

{
  "description": "This token needs to be rotated by the 4th of March this year"
   "roles": [
    "ORG-ADMIN"
   ]
}

Response:
{
  "id": "string",
  "key": "string",
  "description": "string",
  "is_active": true,
  "created_at": "2023-11-15T16:37:20.698Z",
  "deactivated_at": "2023-11-15T16:37:20.698Z",
  "message": "string"
}

The response will include the newly generated API key. Important: Save this key immediately as it will not be retrievable later. We store the key as a one-way hash for security purposes. If it gets lost, a new one needs to be generated.

3. Using API Keys

Once you have a user-generated API key, you can use it to authenticate your requests to the Shield API endpoints.

Including the API Key in Requests

Include the API key in the headers of your API requests under the Authorization field as a Bearer token.

Example:

GET /api/v2/default_rules
Authorization: Bearer YourAPIKey

Key Management

API Key Limitations

By default, you can create up to 50 API keys. If you require more, please contact the Arthur team.

API Key Visibility

API keys are visible only at the time of creation. Once generated, we store them as a one-way hash for security reasons. Please ensure you save the key immediately as we cannot retrieve it if lost.

Rotating API Keys

For security reasons, you can deactivate an API key at any time. To do this, make a DELETE request to the API endpoint /auth/api_keys/deactivate/{api_key_id} with the Admin Key in the request header and the API key ID to be deactivated.

To regenerate a new API key, make a POST request to the API endpoint /auth/api_keys with the Admin Key in the request header and the API key ID to be regenerated.