API Key Creation & Management

Create, list, update, and revoke GaiaEx API keys. Set IP whitelists, permissions, and view the full audit log.

Create API Key

POST https://openapi.gaiaex.com/v1/trade/api-keys

Create a new API key. The API secret is returned only once in this response.

What an API key can do

API keys have exactly two permission scopes: read and trade. There is no withdrawal scope. API keys cannot deposit, withdraw, transfer on-chain, or swap — those actions require the user's embedded-wallet signature and a passkey step-up and are only available in the mobile app. A compromised API key can trade and read your account data, but it cannot move funds off the platform.

NOTE

API key creation is also performed from the mobile app for first-time users. This REST endpoint is for programmatically rotating additional keys on an already-set-up account.

Request Body:

Field	Type	Required	Description
`label`	string	No	Descriptive label (default: empty)
`permissions`	array	No	List of permissions: `"read"`, `"trade"` (default: `["read"]`)
`ip_whitelist`	array	No	List of allowed IP addresses. Omit for unrestricted.
`expires_days`	int	No	Auto-expire after N days. Omit for no expiration.

Example Request:

{
  "label": "trading-bot-v1",
  "permissions": ["read", "trade"],
  "ip_whitelist": ["203.0.113.50"],
  "expires_days": 90
}

Response:

{
  "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "api_secret": "e87d3c78493c3c77d207ceda1a3677e7b23eebbe64be790987014d27b3fd2b9e",
  "label": "trading-bot-v1",
  "permissions": ["read", "trade"],
  "ip_whitelist": ["203.0.113.50"],
  "created_at": "2026-04-01T12:00:00Z",
  "expires_at": "2026-06-30T12:00:00Z",
  "message": "Store the api_secret securely. It will not be shown again."
}

DANGER

The api_secret is shown only in this response. Copy and store it in a secure location. If lost, you must revoke the key and create a new one.

List API Keys

GET https://openapi.gaiaex.com/v1/trade/api-keys

Returns all API keys for the authenticated user. Secrets are not included.

Response:

{
  "keys": [
    {
      "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "label": "trading-bot-v1",
      "permissions": ["read", "trade"],
      "ip_whitelist": ["203.0.113.50"],
      "created_at": "2026-04-01T12:00:00Z",
      "expires_at": "2026-06-30T12:00:00Z",
      "last_used_at": "2026-04-01T15:30:00Z",
      "is_active": true
    }
  ]
}

Update API Key

PATCH https://openapi.gaiaex.com/v1/trade/api-keys/{api_key}

Update label, permissions, or IP whitelist for an existing key.

Path Parameters:

Parameter	Type	Description
`api_key`	string	The API key to update

Request Body:

Field	Type	Required	Description
`label`	string	No	New label
`permissions`	array	No	New permissions list
`ip_whitelist`	array	No	New IP whitelist

Example — Add trade permission:

{
  "permissions": ["read", "trade"]
}

Response:

{
  "success": true,
  "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "updated_fields": ["permissions"]
}

Revoke API Key

DELETE https://openapi.gaiaex.com/v1/trade/api-keys/{api_key}

Permanently revoke a single API key.

Path Parameters:

Parameter	Type	Description
`api_key`	string	The API key to revoke

Response:

{
  "success": true,
  "message": "API key revoked"
}

Revoke All API Keys

DELETE https://openapi.gaiaex.com/v1/trade/api-keys/all

Revoke all API keys for the authenticated user.

Response:

{
  "success": true,
  "revoked_count": 3
}

Get API Key Audit Log

GET https://openapi.gaiaex.com/v1/trade/api-keys/{api_key}/audit

Returns the usage audit trail for a specific API key.

Path Parameters:

Parameter	Type	Description
`api_key`	string	The API key to audit

Query Parameters:

Parameter	Type	Default	Max	Description
`limit`	int	50	100	Number of audit entries

Response:

{
  "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "audit": [
    {
      "action": "POST /order",
      "ip": "203.0.113.50",
      "timestamp": "2026-04-01T15:30:00Z",
      "status": 200
    }
  ],
  "count": 1
}