API Keys

This guide explains how to manage API keys in the Unified Order Service (UOS).

Authentication Methods

UOS supports two authentication methods:

API Keys (covered in this guide) - For service-to-service integrations
MSAL Authentication - For user-facing applications with Azure AD integration

For information about MSAL authentication, see the Authentication Guide.

API keys are used to authenticate requests to the UOS API for service-to-service integrations and automated systems. Each API key has a scope that determines what operations it can perform and which channels it can access.

API Key Scopes

UOS supports three API key scopes:

Scope	Description
`read`	Can only perform GET operations
`write`	Can perform GET, POST, PUT, PATCH operations
`admin`	Has full access to all operations

Channel-Based Access Control

API keys can be restricted to specific channels through the channel_ids property. This allows you to create keys with granular access control:

Keys with specific channel IDs can only access those channels
Keys with an empty channel_ids array have no channel access
Admin-scoped keys can access all channels regardless of channel_ids

Creating an API Key

Naveo Support Required

API key creation requires system-level authentication and must be performed by the Naveo support team. Contact Naveo Support at gsd@maginus.atlassian.net to request new API keys.

To create a new API key, send a POST request to the /v1/api-keys endpoint. (Requires system-level authentication)

curl -X POST "https://api.uos.example.com/v1/api-keys" \
  -H "Authorization: Bearer SYSTEM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Store Operations Manager",
    "client_name": "SOM",
    "description": "API key for SOM integration",
    "scope": "write",
    "channel_ids": ["channel-123", "channel-456"],
    "created_by": "admin@example.com"
  }'

The response will include the new API key:

{
  "id": "key-uuid",
  "key": "som_xxxxxxxxxxxxx",
  "name": "Store Operations Manager",
  "client_name": "SOM",
  "scope": "write",
  "channel_ids": ["channel-123", "channel-456"],
  "created_at": "2024-03-27T12:00:00Z",
  "is_active": true
}

Listing API Keys

To retrieve a list of all API keys, send a GET request to the /v1/api-keys endpoint. (Requires system-level authentication)

curl -X GET "https://api.uos.example.com/v1/api-keys" \
  -H "Authorization: Bearer SYSTEM_API_TOKEN"

Getting API Key Details

To retrieve details about a specific API key, send a GET request to the /v1/api-keys/{keyId} endpoint. (Requires system-level authentication)

curl -X GET "https://api.uos.example.com/v1/api-keys/key-123" \
  -H "Authorization: Bearer SYSTEM_API_TOKEN"

Updating an API Key

To update an existing API key, send a PUT request to the /v1/api-keys/{keyId} endpoint. (Requires system-level authentication)

curl -X PUT "https://api.uos.example.com/v1/api-keys/key-123" \
  -H "Authorization: Bearer SYSTEM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Key Name",
    "description": "Updated description",
    "scope": "read",
    "channel_ids": ["channel-123"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Deactivating an API Key

To deactivate an API key, send a DELETE request to the /v1/api-keys/{keyId} endpoint. (Requires system-level authentication)

curl -X DELETE "https://api.uos.example.com/v1/api-keys/key-123" \
  -H "Authorization: Bearer SYSTEM_API_TOKEN"

This doesn't actually delete the key but sets its is_active property to false, preventing it from being used for authentication.

API Key Properties

Property	Type	Description
`id`	string	Unique identifier for the API key
`key`	string	The actual API key value (prefixed with client name)
`name`	string	Human-readable name for the API key
`client_name`	string	Name of the client/organization using this API key
`description`	string	Optional description of the API key usage
`scope`	string	Access scope: read, write, or admin
`channel_ids`	array	Array of channel IDs this API key has access to
`created_at`	string	When the API key was created
`expires_at`	string	Optional expiration date for the API key
`last_used_at`	string	When the API key was last used
`created_by`	string	Who created this API key
`is_active`	boolean	Whether the API key is currently active
`metadata`	object	Additional metadata about the API key

Best Practices

Security

Use the principle of least privilege - assign the minimum scope necessary
Regularly rotate API keys to minimize security risks
Set expiration dates for temporary access
Deactivate unused keys
Never share API keys between different applications or users

Organization

Use descriptive names for easy identification
Include the purpose or application in the description
Use client_name as a prefix for better key organization
Document who requested each key and for what purpose

Monitoring

Review the last_used_at property to identify inactive keys
Monitor API key usage through server logs
Set up alerts for unusual API key usage patterns
Conduct regular audits of active API keys