How to Create API Credentials

This guide shows you how to create API credentials for accessing Arctic agents programmatically.

Before You Start

Ensure you have:

• Admin access to an Arctic agent (credentials.write scope)
• Knowledge of which scopes the new credentials should have

Create Credentials

With Full Access

Create credentials with full administrative access:

arctic credentials create

When no scopes are specified, credentials receive the urn:tillered:arctic:admin scope (full access).

With Specific Scopes

Create credentials limited to specific operations:

arctic credentials create \
  urn:tillered:arctic:peers.read \
  urn:tillered:arctic:services.read

Available Scopes

Save the Credentials

The response includes the client secret, which is only shown once:

{
  "client_id": "cl_01HXYZ...",
  "client_secret": "sec_abc123...",
  "scopes": ["urn:tillered:arctic:peers.read"],
  "created_at": "2024-01-15T10:30:00Z"
}

Important: Store the client_secret securely. You cannot retrieve it later.

Use the Credentials

Get an Access Token

Exchange credentials for an access token:

curl -X POST http://AGENT_IP:8080/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Make API Requests

Use the access token in the Authorization header:

curl -X GET http://AGENT_IP:8080/v1/peers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Common Use Cases

Read-Only Monitoring

For dashboards or monitoring tools:

arctic credentials create \
  urn:tillered:arctic:peers.read \
  urn:tillered:arctic:services.read

Service Management Only

For automation that manages services:

arctic credentials create \
  urn:tillered:arctic:services.read \
  urn:tillered:arctic:services.write

Peer Management Only

For tools that manage cluster membership:

arctic credentials create \
  urn:tillered:arctic:peers.read \
  urn:tillered:arctic:peers.write

List Existing Credentials

View all credentials for the current license:

arctic credentials list

Note: The client secret is not included in the list response.

Troubleshooting

Invalid Scope

If you receive an error about invalid scopes:

1. Verify the scope URN is spelled correctly
2. Check available scopes in the table above
3. Ensure scopes are space-separated (CLI) or an array (API)

Permission Denied

If you cannot create credentials:

1. Verify your current credentials have credentials.write scope
2. Check you are using an unexpired token

Related

• Rotate Credentials
• Revoke Credentials
• API Authentication