Essence API Key Management

Version v1 · OpenAPI 3.0.1 · 18 operations · Download the JSON document

API key management service for the Essence API Platform (EPIC 8)

Generated from the ApiKeyManagement service's code at build time (api-specs/generated/ApiKeyManagement/Essence.Api.KeyManagement.Api.json) and drift-checked in CI. It describes what the code registers, which is not the same as what any one deployment has routed.

ApiKeys

GET/api/v1/api-keys

Gets all API keys for the authenticated user

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`pageNumber`	query	`integer (int32)`	no	—
`pageSize`	query	`integer (int32)`	no	—

Request body

No request body.

Responses

200Success — ApiKeyDtoPaginatedResponse

POST/api/v1/api-keys

Creates a new API key. The plain key is returned ONCE in the response and cannot be retrieved again.

Authentication:Bearer (the document-wide requirement)

Parameters

Takes no parameters.

Request body

Not marked as required in the document.

CreateApiKeyRequest as application/*+json, application/json, text/json

Responses

201Created — CreateApiKeyResponse

400Bad Request — ProblemDetails

POST/api/v1/api-keys/introspect

Says whether a presented key is live and usable for one scope, and which organisation it acts for — WITHOUT recording a request against it (#10370).

For a backend that authenticates a key for itself rather than trusting an identity the edge forwards (EPIC 51's compliance gate). The edge's `validate` has already metered the request; this one must not meter it twice. Restricted to service callers holding `apikey.introspect`: plain `[Authorize]` would let any signed-in user test key guesses here without a single request ever being counted against them.

Authentication:Bearer (the document-wide requirement)

Parameters

Takes no parameters.

Request body

Not marked as required in the document.

IntrospectApiKeyRequest as application/*+json, application/json, text/json

Responses

200Success — ApiKeyIntrospectionResultDto

400Bad Request — ProblemDetails

403Forbidden — ProblemDetails

GET/api/v1/api-keys/usage

Rolls up consumption across every key the calling developer holds.

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`developerId`	query	`string (uuid)`	no	Optional, and must be the caller's own id when supplied. The console passes it explicitly; accepting an arbitrary value would turn this into a read of anyone's consumption pattern, which reveals their traffic volume and outage windows.

Request body

No request body.

Responses

200Success — AccountUsageDto

403Forbidden — ProblemDetails

POST/api/v1/api-keys/validate

Validates an API key (used by the API gateway for key-based authentication). Uses CryptographicOperations.FixedTimeEquals for constant-time comparison (SEC-005).

Authentication:Bearer (the document-wide requirement)

Parameters

Takes no parameters.

Request body

Not marked as required in the document.

ValidateApiKeyRequest as application/*+json, application/json, text/json

Responses

200Success — ApiKeyValidationResultDto

400Bad Request — ProblemDetails

GET/api/v1/api-keys/{id}

Gets an API key by ID

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`id`	path	`string (uuid)`	yes	—

Request body

No request body.

Responses

200Success — ApiKeyDto

404Not Found — ProblemDetails

DELETE/api/v1/api-keys/{id}

Revokes an API key

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`id`	path	`string (uuid)`	yes	—

Request body

Not marked as required in the document.

RevokeApiKeyRequest as application/*+json, application/json, text/json

Responses

204No Content

404Not Found — ProblemDetails

POST/api/v1/api-keys/{id}/rotate

Rotates an API key (creates a new key with the same properties and revokes the old one — at once, or after an optional overlap of up to 24 hours during which both validate). The new plain key is returned ONCE in the response.

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`id`	path	`string (uuid)`	yes	—

Request body

Not marked as required in the document.

RotateApiKeyRequest as application/*+json, application/json, text/json

Responses

200Success — RotateApiKeyResponse

404Not Found — ProblemDetails

GET/api/v1/api-keys/{id}/usage

Reports one key's consumption against its quota (FR-25.009.5): requests today, the enforced daily ceiling, current burst pressure, whether the key is being throttled right now and on which dimension, and a seven-day trend.

Answers 404 both when the key does not exist and when it is not the caller's, so the response cannot be used to enumerate key ids.

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`id`	path	`string (uuid)`	yes	—

Request body

No request body.

Responses

200Success — KeyUsageDto

404Not Found — ProblemDetails

ApiVersions

GET/api/v1/versions

The publisher version catalogue (FR-08.050).

Authentication:Bearer (the document-wide requirement)

Parameters

Takes no parameters.

Request body

No request body.

Responses

200Success — ApiVersionDto[]

GET/api/v1/versions/pending-sunsets

Pending sunsets affecting a developer's applications (FR-08.039).

developerId is accepted for the console's query-string contract but is NOT the identity: a developer may only read their own pending sunsets, so a value other than the caller's own is refused rather than honoured. Trusting it would turn a convenience parameter into a cross-tenant read of another developer's integration inventory — which endpoints they call, and on which versions.

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`developerId`	query	`string (uuid)`	no	—

Request body

No request body.

Responses

200Success — PendingSunsetDto[]

403Forbidden — ProblemDetails

POST/api/v1/versions/{version}/acknowledge

The maintainer acknowledges the sunset notice (FR-08.051).

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	yes	—

Request body

Not marked as required in the document.

AcknowledgeSunsetRequest as application/*+json, application/json, text/json

Responses

200Success — PendingSunsetDto

404Not Found — ProblemDetails

POST/api/v1/versions/{version}/consumers/{principalId}/extension

Grants one consumer a grace extension past the sunset date.

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	yes	—
`principalId`	path	`string (uuid)`	yes	—

Request body

Not marked as required in the document.

GrantExtensionRequest as application/*+json, application/json, text/json

Responses

204No Content

404Not Found — ProblemDetails

POST/api/v1/versions/{version}/deprecate

Declares a version deprecated (FR-08.050).

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	yes	—

Request body

Not marked as required in the document.

DeclareDeprecationRequest as application/*+json, application/json, text/json

Responses

200Success — ApiVersionDto

400Bad Request — ProblemDetails

409Conflict — ProblemDetails

422The sunset date is inside the 12-month floor (`sunset_floor_violation`). — ProblemDetails

GET/api/v1/versions/{version}/deprecation-report

The read-only governance/audit bundle (FR-08.053).

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	yes	—

Request body

No request body.

Responses

200Success — DeprecationReportDto

404Not Found — ProblemDetails

GET/api/v1/versions/{version}/migration-progress

Per-consumer migration progress (FR-08.051).

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	yes	—

Request body

No request body.

Responses

200Success — MigrationProgressDto

404Not Found — ProblemDetails

POST/api/v1/versions/{version}/notify

Sends or re-sends the deprecation notice campaign (FR-08.050 → EPIC 66).

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	yes	—

Request body

Not marked as required in the document.

NotifyCampaignRequest as application/*+json, application/json, text/json

Responses

200Success — NotifyCampaignResponse

404Not Found — ProblemDetails

409Conflict — ProblemDetails

POST/api/v1/versions/{version}/retire

Retires a version, subject to the zero-traffic gate (FR-08.052).

Authentication:Bearer (the document-wide requirement)

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	yes	—

Request body

Not marked as required in the document.

RetireVersionRequest as application/*+json, application/json, text/json

Responses

200Success — RetireVersionResponse

404Not Found — ProblemDetails

409Live traffic or unacknowledged consumers remain (`version_still_in_use`). — ProblemDetails

Schemas

AccountUsageDto

Property	Type	Required	Description
`developerId`	`string (uuid)`	no	—
`keys`	`KeyUsageDto[] \| null`	no	—
`organizationId`	`string (uuid) \| null`	no	—
`overageAccruedMinor`	`integer (int64) \| null`	no	—
`overageCeilingMinor`	`integer (int64) \| null`	no	—
`overageCurrency`	`string \| null`	no	—
`overageRequests`	`integer (int64)`	no	—
`periodEnd`	`string (date-time)`	no	—
`periodStart`	`string (date-time)`	no	—

AcknowledgeSunsetRequest

Property	Type	Required	Description
`applicationId`	`string (uuid)`	no	—

ApiKeyDto

Property	Type	Required	Description
`createdAt`	`string (date-time)`	no	—
`description`	`string \| null`	no	—
`expiresAt`	`string (date-time) \| null`	no	—
`failedRequests`	`integer (int64)`	no	—
`id`	`string (uuid)`	no	—
`ipWhitelist`	`string[] \| null`	no	—
`keyPrefix`	`string \| null`	no	—
`lastRotatedAt`	`string (date-time) \| null`	no	—
`lastUsedAt`	`string (date-time) \| null`	no	—
`name`	`string \| null`	no	—
`requestsPerDay`	`integer (int32)`	no	—
`requestsPerHour`	`integer (int32)`	no	—
`requestsPerMinute`	`integer (int32)`	no	—
`revokedAt`	`string (date-time) \| null`	no	—
`revokedReason`	`string \| null`	no	—
`rotationOverlapEndsAt`	`string (date-time) \| null`	no	—
`scopes`	`string[] \| null`	no	—
`status`	`string \| null`	no	—
`supersededByKeyId`	`string (uuid) \| null`	no	—
`tier`	`string \| null`	no	—
`totalRequests`	`integer (int64)`	no	—
`userId`	`string (uuid)`	no	—

ApiKeyDtoPaginatedResponse

Property	Type	Required	Description
`hasNextPage`	`boolean`	no	—
`hasPreviousPage`	`boolean`	no	—
`items`	`ApiKeyDto[] \| null`	no	—
`pageNumber`	`integer (int32)`	no	—
`pageSize`	`integer (int32)`	no	—
`totalCount`	`integer (int32)`	no	—
`totalPages`	`integer (int32)`	no	—

ApiKeyIntrospectionResultDto

Property	Type	Required	Description
`active`	`boolean`	no	—
`apiKeyId`	`string (uuid) \| null`	no	—
`organizationId`	`string (uuid) \| null`	no	—
`scopes`	`string[] \| null`	no	—

ApiKeyValidationResultDto

Property	Type	Required	Description
`apiKeyId`	`string (uuid) \| null`	no	—
`breachedDimension`	`string \| null`	no	—
`burstUsedThisMinute`	`integer (int32) \| null`	no	—
`dailyResetAt`	`string (date-time) \| null`	no	—
`failureReason`	`string \| null`	no	—
`insufficientScope`	`boolean`	no	—
`isValid`	`boolean`	no	—
`requestsPerDay`	`integer (int32) \| null`	no	—
`requestsPerDayLimit`	`integer (int64) \| null`	no	—
`requestsPerHour`	`integer (int32) \| null`	no	—
`requestsPerMinute`	`integer (int32) \| null`	no	—
`requestsToday`	`integer (int64) \| null`	no	—
`requiredScope`	`string \| null`	no	—
`retryAfterSeconds`	`integer (int32) \| null`	no	—
`scopes`	`string[] \| null`	no	—
`throttled`	`boolean`	no	—
`tier`	`string \| null`	no	—
`userId`	`string (uuid) \| null`	no	—

ApiVersionDto

Property	Type	Required	Description
`changeClass`	`string \| null`	no	—
`decisionRegisterRef`	`string \| null`	no	—
`deprecatedAt`	`string (date-time) \| null`	no	—
`migrationGuideUrl`	`string \| null`	no	—
`remainingConsumers`	`integer (int32)`	no	—
`replacementVersion`	`string \| null`	no	—
`status`	`string \| null`	no	—
`sunsetAt`	`string (date-time) \| null`	no	—
`version`	`string \| null`	no	—

ConsumerMigrationRowDto

Property	Type	Required	Description
`ackState`	`string \| null`	no	—
`applicationName`	`string \| null`	no	—
`calls30d`	`integer (int64)`	no	—
`extensionUntil`	`string (date-time) \| null`	no	—
`lastSeenAt`	`string (date-time) \| null`	no	—
`maintainerEmail`	`string \| null`	no	—
`migrated`	`boolean`	no	—
`principalId`	`string (uuid)`	no	—

CreateApiKeyRequest

Property	Type	Required	Description
`description`	`string \| null`	no	—
`expiresAt`	`string (date-time) \| null`	no	—
`name`	`string \| null`	no	—
`scopes`	`string[] \| null`	no	—
`tier`	`string \| null`	no	—

CreateApiKeyResponse

Property	Type	Required	Description
`apiKey`	`string \| null`	no	—
`createdAt`	`string (date-time)`	no	—
`expiresAt`	`string (date-time) \| null`	no	—
`id`	`string (uuid)`	no	—
`keyPrefix`	`string \| null`	no	—
`name`	`string \| null`	no	—
`scopes`	`string[] \| null`	no	—
`tier`	`string \| null`	no	—

DeclareDeprecationRequest

Property	Type	Required	Description
`changeClass`	`string \| null`	no	—
`deprecationDate`	`string (date-time)`	no	—
`migrationGuideUrl`	`string \| null`	no	—
`rationale`	`string \| null`	no	—
`replacementVersion`	`string \| null`	no	—
`sunsetDate`	`string (date-time)`	no	—

DeprecationDecisionDto

Property	Type	Required	Description
`changeClass`	`string \| null`	no	—
`decidedAt`	`string (date-time)`	no	—
`decidedBy`	`string \| null`	no	—
`decisionRegisterRef`	`string \| null`	no	—
`rationale`	`string \| null`	no	—

DeprecationReportDto

Property	Type	Required	Description
`decision`	`DeprecationDecisionDto`	no	—
`notificationEvidence`	`NotificationEvidenceDto`	no	—
`parity`	`SurfaceParityDto[] \| null`	no	—
`version`	`string \| null`	no	—
`zeroTrafficRecord`	`ZeroTrafficRecordDto`	no	—

GrantExtensionRequest

Property	Type	Required	Description
`reason`	`string \| null`	no	—
`until`	`string (date-time)`	no	—

IntrospectApiKeyRequest

Property	Type	Required	Description
`apiKey`	`string \| null`	no	—
`requiredScope`	`string \| null`	no	—

KeyUsageDto

Property	Type	Required	Description
`applicationId`	`string (uuid)`	no	—
`applicationName`	`string \| null`	no	—
`breachedDimension`	`string \| null`	no	—
`burstPerMinuteLimit`	`integer (int32)`	no	—
`burstUsedThisMinute`	`integer (int32)`	no	—
`dailyResetAt`	`string (date-time)`	no	—
`keyId`	`string (uuid)`	no	—
`requestsPerDayLimit`	`integer (int64) \| null`	no	—
`requestsToday`	`integer (int64)`	no	—
`retryAfterSeconds`	`integer (int32) \| null`	no	—
`throttledNow`	`boolean`	no	—
`tierCode`	`string \| null`	no	—
`trend7Day`	`UsageTrendPointDto[] \| null`	no	—

MigrationProgressDto

Property	Type	Required	Description
`consumers`	`ConsumerMigrationRowDto[] \| null`	no	—
`liveRequestsInWindow`	`integer (int64)`	no	—
`measurementWindowDays`	`integer (int32)`	no	—
`version`	`string \| null`	no	—

NotificationEvidenceDto

Property	Type	Required	Description
`acknowledged`	`integer (int32)`	no	—
`correlationId`	`string \| null`	no	—
`delivered`	`integer (int32)`	no	—
`failed`	`integer (int32)`	no	—
`notAcknowledged`	`integer (int32)`	no	—
`totalRecipients`	`integer (int32)`	no	—

NotifyCampaignRequest

Property	Type	Required	Description
`audience`	`string \| null`	no	—
`reminderCadence`	`string[] \| null`	no	—

NotifyCampaignResponse

Property	Type	Required	Description
`correlationId`	`string \| null`	no	—
`recipients`	`integer (int32)`	no	—

PendingSunsetDto

Property	Type	Required	Description
`ackState`	`string \| null`	no	—
`applicationId`	`string (uuid)`	no	—
`applicationName`	`string \| null`	no	—
`deprecatedAt`	`string (date-time) \| null`	no	—
`endpointsCalled`	`string[] \| null`	no	—
`measurementWindowDays`	`integer (int32)`	no	—
`migrated`	`boolean`	no	—
`migrationGuideUrl`	`string \| null`	no	—
`replacementVersion`	`string \| null`	no	—
`sunsetAt`	`string (date-time)`	no	—
`version`	`string \| null`	no	—

ProblemDetails

Property	Type	Required	Description
`detail`	`string \| null`	no	—
`instance`	`string \| null`	no	—
`status`	`integer (int32) \| null`	no	—
`title`	`string \| null`	no	—
`type`	`string \| null`	no	—

RetireVersionRequest

Property	Type	Required	Description
`force`	`boolean`	no	—
`signOffRationale`	`string \| null`	no	—

RetireVersionResponse

Property	Type	Required	Description
`retiredAt`	`string (date-time)`	no	—
`zeroTrafficVerifiedAt`	`string (date-time)`	no	—

RevokeApiKeyRequest

Property	Type	Required	Description
`reason`	`string \| null`	no	—

RotateApiKeyRequest

Property	Type	Required	Description
`overlapHours`	`integer (int32)`	no	—

RotateApiKeyResponse

Property	Type	Required	Description
`apiKey`	`string \| null`	no	—
`createdAt`	`string (date-time)`	no	—
`expiresAt`	`string (date-time) \| null`	no	—
`keyPrefix`	`string \| null`	no	—
`newKeyId`	`string (uuid)`	no	—
`oldKeyId`	`string (uuid)`	no	—
`previousKeyValidUntil`	`string (date-time) \| null`	no	—

SurfaceParityDto

Property	Type	Required	Description
`deprecated`	`boolean`	no	—
`detail`	`string \| null`	no	—
`surface`	`string \| null`	no	—

UsageTrendPointDto

Property	Type	Required	Description
`date`	`string \| null`	no	—
`requests`	`integer (int64)`	no	—
`throttledRequests`	`integer (int64)`	no	—

ValidateApiKeyRequest

Property	Type	Required	Description
`apiKey`	`string \| null`	no	—
`endpoint`	`string \| null`	no	—
`ipAddress`	`string \| null`	no	—
`requestedVersion`	`string \| null`	no	—
`requiredScope`	`string \| null`	no	—

ZeroTrafficRecordDto

Property	Type	Required	Description
`liveRequestsInWindow`	`integer (int64)`	no	—
`measurementWindowDays`	`integer (int32)`	no	—
`verifiedAt`	`string (date-time)`	no	—

Essence API Key Management ​

ApiKeys

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

ApiVersions

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Parameters

Request body

Responses

Schemas

AccountUsageDto

AcknowledgeSunsetRequest

ApiKeyDto

ApiKeyDtoPaginatedResponse

ApiKeyIntrospectionResultDto

ApiKeyValidationResultDto

ApiVersionDto

ConsumerMigrationRowDto

CreateApiKeyRequest

CreateApiKeyResponse

DeclareDeprecationRequest

DeprecationDecisionDto

DeprecationReportDto

GrantExtensionRequest

IntrospectApiKeyRequest

KeyUsageDto

MigrationProgressDto

NotificationEvidenceDto

NotifyCampaignRequest

NotifyCampaignResponse

PendingSunsetDto

ProblemDetails

Essence API Key Management