API Keys¶

List all API keys for the current user¶

GET /api-keys

Code samples

curl -X GET https://localhost:9543/api/v0.9/api-keys \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Lists every API key created by the authenticated user across all APIs in the organization. Powers the Developer Portal's global "API Keys" page. Each item additionally carries the owning API's name, version, and type. Secret material is never returned.

Authentication¶

Parameters

Name	In	Type	Required	Description
limit	query	integer	false	Maximum number of records to return.
offset	query	integer	false	Number of records to skip before returning results.

Example responses

200 Response

{
  "list": [
    {
      "id": "weather_prod_key",
      "displayName": "Weather Prod Key",
      "apiId": "weather-api-v1",
      "appId": "my-weather-app",
      "appDisplayName": "My Mobile App",
      "status": "ACTIVE",
      "expiresAt": "2026-12-31T23:59:59Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "revokedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "count": 1,
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	List of API key metadata records.	Inline
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[ApiKeyMetadataResponse]	false	none	[API key metadata returned by list operations. Secret material is omitted.]
»» id	string	false	none	none
»» displayName	string	false	none	none
»» apiId	string	false	none	Developer Portal API ID the key belongs to.
»» appId	string¦null	false	none	ID of the application this key is associated with, if any. Analytics attribution only.
»» appDisplayName	string¦null	false	none	Display name of the associated application, if any.
»» status	string	false	none	none
»» expiresAt	string(date-time)¦null	false	none	none
»» createdAt	string(date-time)	false	none	none
»» revokedAt	string(date-time)¦null	false	none	none
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Enumerated Values

Property	Value
status	ACTIVE
status	REVOKED

Enumerated Values

Property	Value
status	error

Generate an API key¶

POST /apis/{apiId}/api-keys/generate

Code samples

curl -X POST https://localhost:9543/api/v0.9/apis/{apiId}/api-keys/generate \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Generates an API key stored in the Developer Portal (devportal is source of truth). The plaintext secret is returned once in the response and never persisted. A apikey.generated webhook event is published to the organization's configured webhook subscribers so they can register the key (e.g. with a gateway). Key id must match ^[a-z0-9][a-z0-9_-]{0,127}$, and expiresAt must include a timezone when sent as an ISO-8601 string.

Payload

{
  "id": "weather_prod_key",
  "expiresAt": "2026-12-31T23:59:59Z"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	ApiKeyRequest	true	API key payload. `id` must be lowercase and may contain numbers, underscores, and hyphens. `displayName` is an optional human-readable label that defaults to `id` when omitted. `expiresAt` can be an ISO-8601 datetime with timezone, epoch seconds, or epoch milliseconds. The parent resource (API or MCP server, depending on the path) is identified by the corresponding path parameter.
apiId	path	string	true	The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.

Example responses

201 Response

{
  "id": "weather_prod_key",
  "displayName": "Weather Prod Key",
  "key": "ak_dGhpcyBpcyBub3QgYSByZWFsIGtleQ",
  "expiresAt": "2026-12-31T23:59:59Z",
  "status": "ACTIVE"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "Write operations are disabled in read-only mode."
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
201	Created	Generated API key. The plaintext `key` is returned exactly once.	ApiKeyResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
403	Forbidden	Request is forbidden for the current runtime mode or caller permissions.	ErrorResponse
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Response Headers¶

Status	Header	Type	Format	Description
201	Location	string	uri	URL of the generated API key resource.

List API keys¶

GET /apis/{apiId}/api-keys

Code samples

curl -X GET https://localhost:9543/api/v0.9/apis/{apiId}/api-keys \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Lists API keys for the given API.

Authentication¶

Parameters

Name	In	Type	Required	Description
appId	query	string	false	Optional application ID used to filter API keys associated with that application.
limit	query	integer	false	Maximum number of records to return.
offset	query	integer	false	Number of records to skip before returning results.
apiId	path	string	true	The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.

Example responses

200 Response

{
  "list": [
    {
      "id": "weather_prod_key",
      "displayName": "Weather Prod Key",
      "apiId": "weather-api-v1",
      "appId": "my-weather-app",
      "appDisplayName": "My Mobile App",
      "status": "ACTIVE",
      "expiresAt": "2026-12-31T23:59:59Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "revokedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "count": 1,
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	List of API key metadata records.	Inline
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[ApiKeyMetadataResponse]	false	none	[API key metadata returned by list operations. Secret material is omitted.]
»» id	string	false	none	none
»» displayName	string	false	none	none
»» apiId	string	false	none	Developer Portal API ID the key belongs to.
»» appId	string¦null	false	none	ID of the application this key is associated with, if any. Analytics attribution only.
»» appDisplayName	string¦null	false	none	Display name of the associated application, if any.
»» status	string	false	none	none
»» expiresAt	string(date-time)¦null	false	none	none
»» createdAt	string(date-time)	false	none	none
»» revokedAt	string(date-time)¦null	false	none	none
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Enumerated Values

Property	Value
status	ACTIVE
status	REVOKED

Enumerated Values

Property	Value
status	error

Regenerate an API key¶

POST /apis/{apiId}/api-keys/regenerate

Code samples

curl -X POST https://localhost:9543/api/v0.9/apis/{apiId}/api-keys/regenerate \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Regenerates the secret for an existing API key identified by keyId in the request body. An apikey.regenerated webhook event is published to the organization's configured webhook subscribers so they can invalidate the old secret (e.g. at a gateway). The new plaintext secret is returned once and never persisted.

Payload

{
  "keyId": "weather_prod_key",
  "expiresAt": "2027-01-01T00:00:00Z"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	object	true	Identifies the API key to regenerate by its `keyId`. `expiresAt` is optional and, if provided, updates the key's expiry; the key's `id`/`displayName` cannot be changed by this operation.
» keyId	body	string	true	The key's handle — the `id` returned by generate or list.
» expiresAt	body	any	false	New expiry for the key. Can be an ISO-8601 datetime with timezone, epoch seconds, or epoch milliseconds. Omit to leave the current expiry unchanged.
»» anonymous	body	string(date-time)	false	none
»» anonymous	body	number	false	none
apiId	path	string	true	The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.

Example responses

200 Response

{
  "id": "weather_prod_key",
  "displayName": "Weather Prod Key",
  "key": "ak_dGhpcyBpcyBub3QgYSByZWFsIGtleQ",
  "expiresAt": "2026-12-31T23:59:59Z",
  "status": "ACTIVE"
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "Write operations are disabled in read-only mode."
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Cannot regenerate a revoked key"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Generated or regenerated API key. The plaintext `key` is returned exactly once.	ApiKeyResponse
403	Forbidden	Request is forbidden for the current runtime mode or caller permissions.	ErrorResponse
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The key has already been revoked and cannot be regenerated.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Revoke an API key¶

POST /apis/{apiId}/api-keys/revoke

Code samples

curl -X POST https://localhost:9543/api/v0.9/apis/{apiId}/api-keys/revoke \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Revokes an existing API key identified by keyId in the request body. An apikey.revoked webhook event is published to the organization's configured webhook subscribers so they can immediately reject requests carrying the key (e.g. at a gateway).

Payload

{
  "keyId": "weather_prod_key"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	object	true	Identifies the API key to revoke by its `keyId`.
» keyId	body	string	true	The key's handle — the `id` returned by generate or list.
apiId	path	string	true	The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.

Example responses

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "Write operations are disabled in read-only mode."
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Key already revoked or not found"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
204	No Content	API key revoked successfully.	None
403	Forbidden	Request is forbidden for the current runtime mode or caller permissions.	ErrorResponse
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The key has already been revoked.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Associate an API key with an application¶

POST /apis/{apiId}/api-keys/associate

Code samples

curl -X POST https://localhost:9543/api/v0.9/apis/{apiId}/api-keys/associate \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Associates (or re-associates) an existing API key with an application, for analytics attribution only — it has no effect on the key's validity or authorization. An apikey.application_updated webhook event is published once for this key, with a payload of { key_id, application }.

Payload

{
  "keyId": "weather_prod_key",
  "appId": "my-weather-app"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	object	true	Identifies the API key and the application to associate it with.
» keyId	body	string	true	The key's handle — the `id` returned by generate or list.
» appId	body	string	true	Developer Portal application ID to associate the key with.
apiId	path	string	true	The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.

Example responses

200 Response

{
  "application": {
    "id": "my-weather-app",
    "displayName": "My Mobile App"
  }
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "Write operations are disabled in read-only mode."
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Cannot associate a revoked key"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Association updated.	ApiKeyApplicationResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
403	Forbidden	Request is forbidden for the current runtime mode or caller permissions.	ErrorResponse
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The key has already been revoked and cannot be associated with an application.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Remove an API key's application association¶

POST /apis/{apiId}/api-keys/dissociate

Code samples

curl -X POST https://localhost:9543/api/v0.9/apis/{apiId}/api-keys/dissociate \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Removes the application association from an API key identified by keyId in the request body, if any. An apikey.application_updated webhook event is published once for this key, with application set to null.

Payload

{
  "keyId": "weather_prod_key"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	object	true	Identifies the API key to remove the application association from.
» keyId	body	string	true	The key's handle — the `id` returned by generate or list.
apiId	path	string	true	The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.

Example responses

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "Write operations are disabled in read-only mode."
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
204	No Content	Association removed (or none existed).	None
403	Forbidden	Request is forbidden for the current runtime mode or caller permissions.	ErrorResponse
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

List API keys associated with an application¶

GET /applications/{applicationId}/api-keys

Code samples

curl -X GET https://localhost:9543/api/v0.9/applications/{applicationId}/api-keys \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Lists all API keys (across every API) currently associated with the given application. Unlike listApiKeys, no apiId filter is required.

Authentication¶

Parameters

Name	In	Type	Required	Description
limit	query	integer	false	Maximum number of records to return.
offset	query	integer	false	Number of records to skip before returning results.
applicationId	path	string	true	The application's handle (unique per org).

Example responses

200 Response

{
  "list": [
    {
      "id": "weather_prod_key",
      "displayName": "Weather Prod Key",
      "apiId": "weather-api-v1",
      "appId": "my-weather-app",
      "appDisplayName": "My Mobile App",
      "status": "ACTIVE",
      "expiresAt": "2026-12-31T23:59:59Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "revokedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "count": 1,
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	List of API key metadata records.	Inline
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[ApiKeyMetadataResponse]	false	none	[API key metadata returned by list operations. Secret material is omitted.]
»» id	string	false	none	none
»» displayName	string	false	none	none
»» apiId	string	false	none	Developer Portal API ID the key belongs to.
»» appId	string¦null	false	none	ID of the application this key is associated with, if any. Analytics attribution only.
»» appDisplayName	string¦null	false	none	Display name of the associated application, if any.
»» status	string	false	none	none
»» expiresAt	string(date-time)¦null	false	none	none
»» createdAt	string(date-time)	false	none	none
»» revokedAt	string(date-time)¦null	false	none	none
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Enumerated Values

Property	Value
status	ACTIVE
status	REVOKED