API Keys Reference

This page documents the API Keys endpoints in the Core API.

List API Keys

Returns a list of all API keys.

URL: /v1/api-keys

Method: GET

Auth required: Yes (system authentication)

Example Request:

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

Success Response:

Code: 200 OK
Content:

{
  "data": [
    {
      "id": "key-123",
      "key": "som_xxxxx",
      "name": "Store Operations Manager",
      "client_name": "SOM",
      "description": "API key for SOM integration",
      "scope": "write",
      "channel_ids": ["channel-123", "channel-456"],
      "created_at": "2023-06-01T10:00:00Z",
      "expires_at": "2024-06-01T10:00:00Z",
      "last_used_at": "2023-06-01T12:00:00Z",
      "created_by": "admin@example.com",
      "is_active": true
    },
    {
      "id": "key-456",
      "key": "pos_xxxxx",
      "name": "Point of Sale Integration",
      "client_name": "POS",
      "description": "API key for POS integration",
      "scope": "read",
      "channel_ids": ["channel-123"],
      "created_at": "2023-06-01T11:00:00Z",
      "expires_at": null,
      "last_used_at": "2023-06-01T14:00:00Z",
      "created_by": "admin@example.com",
      "is_active": true
    }
  ],
  "count": 2
}

Get API Key Details

Returns details about a specific API key.

URL: /v1/api-keys/{keyId}

Method: GET

Auth required: Yes (system authentication)

Example Request:

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

Success Response:

Code: 200 OK
Content:

{
  "id": "key-123",
  "key": "som_xxxxx",
  "name": "Store Operations Manager",
  "client_name": "SOM",
  "description": "API key for SOM integration",
  "scope": "write",
  "channel_ids": ["channel-123", "channel-456"],
  "created_at": "2023-06-01T10:00:00Z",
  "expires_at": "2024-06-01T10:00:00Z",
  "last_used_at": "2023-06-01T12:00:00Z",
  "created_by": "admin@example.com",
  "is_active": true,
  "metadata": {
    "usage_notes": "For store operations management integration"
  }
}

Error Responses:

Code: 404 Not Found
- Content: { "error": "API key not found" }

Create API Key

Creates a new API key.

URL: /v1/api-keys

Method: POST

Auth required: Yes (system authentication)

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Human-readable name for the API key
`client_name`	string	Yes	Name of the client/organization
`description`	string	No	Optional description of the API key usage
`scope`	string	No	Access scope: "read", "write", or "admin" (default: "read")
`channel_ids`	array	No	Channel IDs this key has access to
`expires_at`	string	No	Optional expiration date (ISO 8601 format)
`created_by`	string	Yes	Who is creating this API key
`metadata`	object	No	Additional metadata

Example Request:

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"],
    "expires_at": "2024-06-01T10:00:00Z",
    "created_by": "admin@example.com",
    "metadata": {
      "usage_notes": "For store operations management integration"
    }
  }'

Success Response:

Code: 201 Created
Content:

{
  "id": "key-123",
  "key": "som_a1b2c3d4e5f6g7h8i9j0",
  "name": "Store Operations Manager",
  "client_name": "SOM",
  "description": "API key for SOM integration",
  "scope": "write",
  "channel_ids": ["channel-123", "channel-456"],
  "created_at": "2023-06-01T10:00:00Z",
  "expires_at": "2024-06-01T10:00:00Z",
  "created_by": "admin@example.com",
  "is_active": true,
  "metadata": {
    "usage_notes": "For store operations management integration"
  }
}

Error Responses:

Code: 400 Bad Request
- Content: { "error": "Missing required fields or invalid scope" }

Update API Key

Updates an existing API key configuration.

URL: /v1/api-keys/{keyId}

Method: PUT

Auth required: Yes (system authentication)

Request Body:

Field	Type	Required	Description
`name`	string	No	Human-readable name for the API key
`description`	string	No	Optional description of the API key usage
`scope`	string	No	Access scope: "read", "write", or "admin"
`channel_ids`	array	No	Channel IDs this key has access to
`expires_at`	string	No	Optional expiration date (ISO 8601 format)
`is_active`	boolean	No	Whether the API key is active
`metadata`	object	No	Additional metadata

Example Request:

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": "SOM Integration Key",
    "description": "Updated API key for SOM integration",
    "scope": "write",
    "channel_ids": ["channel-123", "channel-456", "channel-789"],
    "expires_at": "2025-06-01T10:00:00Z",
    "is_active": true
  }'

Success Response:

Code: 200 OK
Content:

{
  "id": "key-123",
  "key": "som_xxxxx",
  "name": "SOM Integration Key",
  "client_name": "SOM",
  "description": "Updated API key for SOM integration",
  "scope": "write",
  "channel_ids": ["channel-123", "channel-456", "channel-789"],
  "created_at": "2023-06-01T10:00:00Z",
  "expires_at": "2025-06-01T10:00:00Z",
  "last_used_at": "2023-06-01T12:00:00Z",
  "created_by": "admin@example.com",
  "is_active": true,
  "updated_at": "2023-06-01T15:00:00Z"
}

Error Responses:

Code: 404 Not Found
- Content: { "error": "API key not found" }

Deactivate API Key

Deactivates an API key (soft delete).

URL: /v1/api-keys/{keyId}

Method: DELETE

Auth required: Yes (system authentication)

Example Request:

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

Success Response:

Code: 204 No Content

Error Responses:

Code: 404 Not Found
- Content: { "error": "API key not found" }

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

Access Scopes

Scope	Description	Permissions
`read`	Read-only access	Can only perform GET operations
`write`	Read and write access	Can perform GET, POST, PUT, PATCH operations
`admin`	Full access	Can perform all operations, including API key management

Empty channel_ids array means no channel access. Admin scope can access all channels regardless of channel_ids.