@unkey/api
Version:
<div align="center"> <h1 align="center">@unkey/api</h1> <h5>`@unkey/api` is a TypeScript client for Unkey. If you prefer a typed experience over calling HTTP endpoints directly, this SDK is for you.</h5> </div>
1,327 lines (1,320 loc) • 236 kB
TypeScript
import { PermissionQuery } from '@unkey/rbac';
export { Flatten, and, or } from '@unkey/rbac';
/**
* This file was auto-generated by openapi-typescript.
* Do not make direct changes to the file.
*/
/** OneOf type helpers */
type Without<T, U> = { [P in Exclude<keyof T, keyof U>]?: never };
type XOR<T, U> = (T | U) extends object ? (Without<T, U> & U) | (Without<U, T> & T) : T | U;
type OneOf<T extends any[]> = T extends [infer Only] ? Only : T extends [infer A, infer B, ...infer Rest] ? OneOf<[XOR<A, B>, ...Rest]> : never;
interface paths {
"/v1/liveness": {
get: operations["v1.liveness"];
};
"/v1/keys.getKey": {
get: operations["getKey"];
};
"/v1/keys.whoami": {
post: operations["whoami"];
};
"/v1/keys.deleteKey": {
post: operations["deleteKey"];
};
"/v1/keys.createKey": {
post: operations["createKey"];
};
"/v1/keys.verifyKey": {
post: operations["verifyKey"];
};
"/v1/keys.updateKey": {
post: operations["updateKey"];
};
"/v1/keys.updateRemaining": {
post: operations["updateRemaining"];
};
"/v1/keys.getVerifications": {
get: operations["keys.getVerifications"];
};
"/v1/keys.addPermissions": {
post: operations["addPermissions"];
};
"/v1/keys.removePermissions": {
post: operations["removePermissions"];
};
"/v1/keys.setPermissions": {
post: operations["setPermissions"];
};
"/v1/keys.addRoles": {
post: operations["addRoles"];
};
"/v1/keys.removeRoles": {
post: operations["removeRoles"];
};
"/v1/keys.setRoles": {
post: operations["setRoles"];
};
"/v1/apis.getApi": {
get: operations["getApi"];
};
"/v1/apis.createApi": {
post: operations["createApi"];
};
"/v1/apis.listKeys": {
get: operations["listKeys"];
};
"/v1/apis.deleteApi": {
post: operations["deleteApi"];
};
"/v1/apis.deleteKeys": {
post: operations["deleteKeys"];
};
"/v1/ratelimits.limit": {
post: operations["limit"];
};
"/v1/ratelimits.setOverride": {
post: operations["setOverride"];
};
"/v1/ratelimits.listOverrides": {
get: operations["listOverrides"];
};
"/v1/ratelimits.deleteOverride": {
post: operations["deleteOverride"];
};
"/v1/ratelimits.getOverride": {
get: operations["getOverride"];
};
"/v1/migrations.createKeys": {
post: operations["v1.migrations.createKeys"];
};
"/v1/migrations.enqueueKeys": {
post: operations["v1.migrations.enqueueKeys"];
};
"/v1/permissions.createPermission": {
post: operations["createPermission"];
};
"/v1/permissions.deletePermission": {
post: operations["deletePermission"];
};
"/v1/permissions.getPermission": {
get: operations["getPermission"];
};
"/v1/permissions.listPermissions": {
get: operations["listPermissions"];
};
"/v1/permissions.createRole": {
post: operations["createRole"];
};
"/v1/permissions.deleteRole": {
post: operations["deleteRole"];
};
"/v1/permissions.getRole": {
get: operations["getRole"];
};
"/v1/permissions.listRoles": {
get: operations["listRoles"];
};
"/v1/identities.createIdentity": {
post: operations["createIdentity"];
};
"/v1/identities.getIdentity": {
get: operations["getIdentity"];
};
"/v1/identities.listIdentities": {
get: operations["listIdentities"];
};
"/v1/identities.updateIdentity": {
post: operations["updateIdentity"];
};
"/v1/identities.deleteIdentity": {
post: operations["deleteIdentity"];
};
"/v1/analytics.getVerifications": {
get: operations["getVerifications"];
};
"/v1/keys": {
post: operations["deprecated.createKey"];
};
"/v1/keys/verify": {
/** @deprecated */
post: operations["deprecated.verifyKey"];
};
"/v1/apis/{apiId}/keys": {
get: operations["deprecated.listKeys"];
};
}
interface components {
schemas: {
ErrBadRequest: {
error: {
/**
* @description A machine readable error code.
* @example BAD_REQUEST
* @enum {string}
*/
code: "BAD_REQUEST";
/**
* @description A link to our documentation with more details about this error code
* @example https://unkey.dev/docs/api-reference/errors/code/BAD_REQUEST
*/
docs: string;
/** @description A human readable explanation of what went wrong */
message: string;
/**
* @description Please always include the requestId in your error report
* @example req_1234
*/
requestId: string;
};
};
ErrUnauthorized: {
error: {
/**
* @description A machine readable error code.
* @example UNAUTHORIZED
* @enum {string}
*/
code: "UNAUTHORIZED";
/**
* @description A link to our documentation with more details about this error code
* @example https://unkey.dev/docs/api-reference/errors/code/UNAUTHORIZED
*/
docs: string;
/** @description A human readable explanation of what went wrong */
message: string;
/**
* @description Please always include the requestId in your error report
* @example req_1234
*/
requestId: string;
};
};
ErrForbidden: {
error: {
/**
* @description A machine readable error code.
* @example FORBIDDEN
* @enum {string}
*/
code: "FORBIDDEN";
/**
* @description A link to our documentation with more details about this error code
* @example https://unkey.dev/docs/api-reference/errors/code/FORBIDDEN
*/
docs: string;
/** @description A human readable explanation of what went wrong */
message: string;
/**
* @description Please always include the requestId in your error report
* @example req_1234
*/
requestId: string;
};
};
ErrNotFound: {
error: {
/**
* @description A machine readable error code.
* @example NOT_FOUND
* @enum {string}
*/
code: "NOT_FOUND";
/**
* @description A link to our documentation with more details about this error code
* @example https://unkey.dev/docs/api-reference/errors/code/NOT_FOUND
*/
docs: string;
/** @description A human readable explanation of what went wrong */
message: string;
/**
* @description Please always include the requestId in your error report
* @example req_1234
*/
requestId: string;
};
};
ErrConflict: {
error: {
/**
* @description A machine readable error code.
* @example CONFLICT
* @enum {string}
*/
code: "CONFLICT";
/**
* @description A link to our documentation with more details about this error code
* @example https://unkey.dev/docs/api-reference/errors/code/CONFLICT
*/
docs: string;
/** @description A human readable explanation of what went wrong */
message: string;
/**
* @description Please always include the requestId in your error report
* @example req_1234
*/
requestId: string;
};
};
ErrPreconditionFailed: {
error: {
/**
* @description A machine readable error code.
* @example PRECONDITION_FAILED
* @enum {string}
*/
code: "PRECONDITION_FAILED";
/**
* @description A link to our documentation with more details about this error code
* @example https://unkey.dev/docs/api-reference/errors/code/PRECONDITION_FAILED
*/
docs: string;
/** @description A human readable explanation of what went wrong */
message: string;
/**
* @description Please always include the requestId in your error report
* @example req_1234
*/
requestId: string;
};
};
ErrTooManyRequests: {
error: {
/**
* @description A machine readable error code.
* @example TOO_MANY_REQUESTS
* @enum {string}
*/
code: "TOO_MANY_REQUESTS";
/**
* @description A link to our documentation with more details about this error code
* @example https://unkey.dev/docs/api-reference/errors/code/TOO_MANY_REQUESTS
*/
docs: string;
/** @description A human readable explanation of what went wrong */
message: string;
/**
* @description Please always include the requestId in your error report
* @example req_1234
*/
requestId: string;
};
};
ErrInternalServerError: {
error: {
/**
* @description A machine readable error code.
* @example INTERNAL_SERVER_ERROR
* @enum {string}
*/
code: "INTERNAL_SERVER_ERROR";
/**
* @description A link to our documentation with more details about this error code
* @example https://unkey.dev/docs/api-reference/errors/code/INTERNAL_SERVER_ERROR
*/
docs: string;
/** @description A human readable explanation of what went wrong */
message: string;
/**
* @description Please always include the requestId in your error report
* @example req_1234
*/
requestId: string;
};
};
Key: {
/**
* @description The id of the key
* @example key_1234
*/
id: string;
/**
* @description The first few characters of the key to visually identify it
* @example sk_5j1
*/
start: string;
/**
* @description The id of the workspace that owns the key
* @example ws_1234
*/
workspaceId: string;
/**
* @description The id of the api that this key is for
* @example api_1234
*/
apiId?: string;
/**
* @description The name of the key, give keys a name to easily identify their purpose
* @example Customer X
*/
name?: string;
/**
* @description The id of the tenant associated with this key. Use whatever reference you have in your system to identify the tenant. When verifying the key, we will send this field back to you, so you know who is accessing your API.
* @example user_123
*/
ownerId?: string;
/**
* @description Any additional metadata you want to store with the key
* @example {
* "roles": [
* "admin",
* "user"
* ],
* "stripeCustomerId": "cus_1234"
* }
*/
meta?: {
[key: string]: unknown;
};
/**
* @description The unix timestamp in milliseconds when the key was created
* @example 0
*/
createdAt: number;
/**
* @description The unix timestamp in milliseconds when the key was last updated
* @example 0
*/
updatedAt?: number;
/**
* @description The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring.
* @example 0
*/
expires?: number;
/**
* @description The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit.
* @example 1000
*/
remaining?: number;
/**
* @description Unkey allows you to refill remaining verifications on a key on a regular interval.
* @example {
* "interval": "monthly",
* "amount": 10,
* "refillDay": 10
* }
*/
refill?: {
/**
* @description Determines the rate at which verifications will be refilled. When 'daily' is set for 'interval' 'refillDay' will be set to null.
* @example daily
* @enum {string}
*/
interval: "daily" | "monthly";
/**
* @description Resets `remaining` to this value every interval.
* @example 100
*/
amount: number;
/**
* @description The day verifications will refill each month, when interval is set to 'monthly'. Value is not zero-indexed making 1 the first day of the month. If left blank it will default to the first day of the month. When 'daily' is set for 'interval' 'refillDay' will be set to null.
* @default 1
* @example 15
*/
refillDay?: number | null;
/**
* @description The unix timestamp in miliseconds when the key was last refilled.
* @example 100
*/
lastRefillAt?: number;
};
/**
* @description Unkey comes with per-key ratelimiting out of the box.
* @example {
* "async": true,
* "limit": 10,
* "duration": 60
* }
*/
ratelimit?: {
async: boolean;
/**
* @description Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.
* @enum {string}
*/
type?: "fast" | "consistent";
/** @description The total amount of burstable requests. */
limit: number;
/** @description How many tokens to refill during each refillInterval. */
refillRate?: number;
/** @description Determines the speed at which tokens are refilled, in milliseconds. */
refillInterval?: number;
/** @description The duration of the ratelimit window, in milliseconds. */
duration: number;
};
/**
* @description All roles this key belongs to
* @example [
* "admin",
* "finance"
* ]
*/
roles?: string[];
/**
* @description All permissions this key has
* @example [
* "domain.dns.create_record",
* "finance.read_receipt"
* ]
*/
permissions?: string[];
/**
* @description Sets if key is enabled or disabled. Disabled keys are not valid.
* @example true
*/
enabled?: boolean;
/** @description The key in plaintext */
plaintext?: string;
/** @description The identity of the key */
identity?: {
/** @description The id of the identity */
id: string;
/** @description The external id of the identity */
externalId: string;
/** @description Any additional metadata attached to the identity */
meta?: {
[key: string]: unknown;
};
};
};
V1KeysVerifyKeyResponse: {
/**
* @description The id of the key
* @example key_1234
*/
keyId?: string;
/**
* @description Whether the key is valid or not.
* A key could be invalid for a number of reasons, for example if it has expired, has no more verifications left or if it has been deleted.
* @example true
*/
valid: boolean;
/**
* @description The name of the key, give keys a name to easily identifiy their purpose
* @example Customer X
*/
name?: string;
/**
* @description The id of the tenant associated with this key. Use whatever reference you have in your system to identify the tenant. When verifying the key, we will send this field back to you, so you know who is accessing your API.
* @example user_123
*/
ownerId?: string;
/**
* @description Any additional metadata you want to store with the key
* @example {
* "roles": [
* "admin",
* "user"
* ],
* "stripeCustomerId": "cus_1234"
* }
*/
meta?: {
[key: string]: unknown;
};
/**
* @description The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring.
* @example 123
*/
expires?: number;
/**
* @description The ratelimit configuration for this key. If this field is null or undefined, the key has no ratelimit.
* @example {
* "limit": 10,
* "remaining": 9,
* "reset": 3600000
* }
*/
ratelimit?: {
/**
* @description Maximum number of requests that can be made inside a window
* @example 10
*/
limit: number;
/**
* @description Remaining requests after this verification
* @example 9
*/
remaining: number;
/**
* @description Unix timestamp in milliseconds when the ratelimit will reset
* @example 3600000
*/
reset: number;
};
/**
* @description The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit.
* @example 1000
*/
remaining?: number;
/**
* @description A machine readable code why the key is not valid.
* Possible values are:
* - VALID: the key is valid and you should proceed
* - NOT_FOUND: the key does not exist or has expired
* - FORBIDDEN: the key is not allowed to access the api
* - USAGE_EXCEEDED: the key has exceeded its request limit
* - RATE_LIMITED: the key has been ratelimited
* - UNAUTHORIZED: the key is not authorized
* - DISABLED: the key is disabled
* - INSUFFICIENT_PERMISSIONS: you do not have the required permissions to perform this action
* - EXPIRED: The key was only valid for a certain time and has expired.
*
* These are validation codes, the HTTP status will be 200.
*
* @enum {string}
*/
code: "VALID" | "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | "INSUFFICIENT_PERMISSIONS" | "EXPIRED";
/** @description Sets the key to be enabled or disabled. Disabled keys will not verify. */
enabled?: boolean;
/**
* @description A list of all the permissions this key is connected to.
* @example [
* "dns.record.update",
* "dns.record.delete"
* ]
*/
permissions?: string[];
/**
* @description A list of all the roles this key is connected to.
* @example [
* "admin"
* ]
*/
roles?: string[];
/**
* @description The environment of the key, this is what what you set when you crated the key
* @example test
*/
environment?: string;
/** @description The associated identity of this key. */
identity?: {
id: string;
externalId: string;
meta: {
[key: string]: unknown;
};
};
/** @description A unique id for this request, please provide it to Unkey support to help us debug your issue. */
requestId: string;
};
/** @description A query for which permissions you require */
PermissionQuery: OneOf<[string, {
and: components["schemas"]["PermissionQuery"][];
}, {
or: components["schemas"]["PermissionQuery"][];
}, null]>;
V1KeysVerifyKeyRequest: {
/**
* @description The id of the api where the key belongs to. This is optional for now but will be required soon.
* The key will be verified against the api's configuration. If the key does not belong to the api, the verification will fail.
* @example api_1234
*/
apiId?: string;
/**
* @description The key to verify
* @example sk_1234
*/
key: string;
/**
* @description Tags do not influence the outcome of a verification.
* They can be added to filter or aggregate historical verification data for your analytics needs.
* To unkey, a tag is simply a string, we don't enforce any schema but leave that up to you.
* The only exception is that each tag must be between 1 and 128 characters long.
* A typical setup would be to add key-value pairs of resources or locations, that you need later when querying.
*
* @example [
* "path=/v1/users/123",
* "region=us-east-1"
* ]
*/
tags?: string[];
/** @description Perform RBAC checks */
authorization?: {
permissions?: components["schemas"]["PermissionQuery"];
};
/** @description Customize the behaviour of deducting remaining uses. When some of your endpoints are more expensive than others, you can set a custom `cost` for each. */
remaining?: {
/**
* @description How many tokens should be deducted from the current `remaining` value. Set it to 0, to make it free.
* @default 1
*/
cost?: number;
};
/**
* @deprecated
* @description Use 'ratelimits' with `[{ name: "default", cost: 2}]`
*/
ratelimit?: {
/**
* @description Override how many tokens are deducted during the ratelimit operation.
* @default 1
*/
cost?: number;
};
/**
* @description You can check against multiple ratelimits when verifying a key. Let's say you are building an app that uses AI under the hood and you want to limit your customers to 500 requests per hour, but also ensure they use up less than 20k tokens per day.
*
* @example [
* {
* "name": "requests",
* "limit": 500,
* "duration": 3600000
* },
* {
* "name": "tokens",
* "limit": 20000,
* "duration": 86400000
* }
* ]
*/
ratelimits?: {
/**
* @description The name of the ratelimit.
* @example tokens
*/
name: string;
/**
* @description Optionally override how expensive this operation is and how many tokens are deducted from the current limit.
* @default 1
*/
cost?: number;
/** @description Optionally override the limit. */
limit?: number;
/** @description Optionally override the ratelimit window duration. */
duration?: number;
}[];
};
ErrDeleteProtected: {
error: {
/**
* @description A machine readable error code.
* @example DELETE_PROTECTED
* @enum {string}
*/
code: "DELETE_PROTECTED";
/**
* @description A link to our documentation with more details about this error code
* @example https://unkey.dev/docs/api-reference/errors/code/DELETE_PROTECTED
*/
docs: string;
/** @description A human readable explanation of what went wrong */
message: string;
/**
* @description Please always include the requestId in your error report
* @example req_1234
*/
requestId: string;
};
};
};
responses: never;
parameters: {
};
requestBodies: never;
headers: never;
pathItems: never;
}
interface operations {
"v1.liveness": {
responses: {
/** @description The configured services and their status */
200: {
content: {
"application/json": {
/** @description The status of the server */
status: string;
services: {
/**
* @description The name of the connected metrics service
* @example AxiomMetrics
*/
metrics: string;
/**
* @description The name of the connected logger service
* @example AxiomLogger or ConsoleLogger
*/
logger: string;
/** @description The name of the connected ratelimit service */
ratelimit: string;
/** @description The name of the connected usagelimit service */
usagelimit: string;
};
};
};
};
/** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
400: {
content: {
"application/json": components["schemas"]["ErrBadRequest"];
};
};
/** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
401: {
content: {
"application/json": components["schemas"]["ErrUnauthorized"];
};
};
/** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
403: {
content: {
"application/json": components["schemas"]["ErrForbidden"];
};
};
/** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
404: {
content: {
"application/json": components["schemas"]["ErrNotFound"];
};
};
/** @description This response is sent when a request conflicts with the current state of the server. */
409: {
content: {
"application/json": components["schemas"]["ErrConflict"];
};
};
/** @description The requested operation cannot be completed because certain conditions were not met. This typically occurs when a required resource state or version check fails. */
412: {
content: {
"application/json": components["schemas"]["ErrPreconditionFailed"];
};
};
/** @description The user has sent too many requests in a given amount of time ("rate limiting") */
429: {
content: {
"application/json": components["schemas"]["ErrTooManyRequests"];
};
};
/** @description The server has encountered a situation it does not know how to handle. */
500: {
content: {
"application/json": components["schemas"]["ErrInternalServerError"];
};
};
};
};
getKey: {
parameters: {
query: {
keyId: string;
decrypt?: boolean | null;
};
};
responses: {
/** @description The configuration for a single key */
200: {
content: {
"application/json": components["schemas"]["Key"];
};
};
/** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
400: {
content: {
"application/json": components["schemas"]["ErrBadRequest"];
};
};
/** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
401: {
content: {
"application/json": components["schemas"]["ErrUnauthorized"];
};
};
/** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
403: {
content: {
"application/json": components["schemas"]["ErrForbidden"];
};
};
/** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
404: {
content: {
"application/json": components["schemas"]["ErrNotFound"];
};
};
/** @description This response is sent when a request conflicts with the current state of the server. */
409: {
content: {
"application/json": components["schemas"]["ErrConflict"];
};
};
/** @description The requested operation cannot be completed because certain conditions were not met. This typically occurs when a required resource state or version check fails. */
412: {
content: {
"application/json": components["schemas"]["ErrPreconditionFailed"];
};
};
/** @description The user has sent too many requests in a given amount of time ("rate limiting") */
429: {
content: {
"application/json": components["schemas"]["ErrTooManyRequests"];
};
};
/** @description The server has encountered a situation it does not know how to handle. */
500: {
content: {
"application/json": components["schemas"]["ErrInternalServerError"];
};
};
};
};
whoami: {
requestBody: {
content: {
"application/json": {
/**
* @description The actual key to fetch
* @example sk_123
*/
key: string;
};
};
};
responses: {
/** @description The configuration for a single key */
200: {
content: {
"application/json": {
/**
* @description The ID of the key
* @example key_123
*/
id: string;
/**
* @description The name of the key
* @example API Key 1
*/
name?: string;
/**
* @description The remaining number of requests for the key
* @example 1000
*/
remaining?: number;
/** @description The identity object associated with the key */
identity?: {
/**
* @description The identity ID associated with the key
* @example id_123
*/
id: string;
/**
* @description The external identity ID associated with the key
* @example ext123
*/
externalId: string;
};
/**
* @description Metadata associated with the key
* @example {
* "role": "admin",
* "plan": "premium"
* }
*/
meta?: {
[key: string]: unknown;
};
/**
* @description The timestamp in milliseconds when the key was created
* @example 1620000000000
*/
createdAt: number;
/**
* @description Whether the key is enabled
* @example true
*/
enabled: boolean;
/**
* @description The environment the key is associated with
* @example production
*/
environment?: string;
};
};
};
/** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
400: {
content: {
"application/json": components["schemas"]["ErrBadRequest"];
};
};
/** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
401: {
content: {
"application/json": components["schemas"]["ErrUnauthorized"];
};
};
/** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
403: {
content: {
"application/json": components["schemas"]["ErrForbidden"];
};
};
/** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
404: {
content: {
"application/json": components["schemas"]["ErrNotFound"];
};
};
/** @description This response is sent when a request conflicts with the current state of the server. */
409: {
content: {
"application/json": components["schemas"]["ErrConflict"];
};
};
/** @description The requested operation cannot be completed because certain conditions were not met. This typically occurs when a required resource state or version check fails. */
412: {
content: {
"application/json": components["schemas"]["ErrPreconditionFailed"];
};
};
/** @description The user has sent too many requests in a given amount of time ("rate limiting") */
429: {
content: {
"application/json": components["schemas"]["ErrTooManyRequests"];
};
};
/** @description The server has encountered a situation it does not know how to handle. */
500: {
content: {
"application/json": components["schemas"]["ErrInternalServerError"];
};
};
};
};
deleteKey: {
requestBody: {
content: {
"application/json": {
/**
* @description The id of the key to revoke
* @example key_1234
*/
keyId: string;
/**
* @description By default Unkey soft deletes keys, so they may be recovered later. If you want to permanently delete it, set permanent=true. This might be necessary if you run into CONFLICT errors during key migration.
* @default false
*/
permanent?: boolean;
};
};
};
responses: {
/** @description The key was successfully revoked, it may take up to 30s for this to take effect in all regions */
200: {
content: {
"application/json": Record<string, never>;
};
};
/** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
400: {
content: {
"application/json": components["schemas"]["ErrBadRequest"];
};
};
/** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
401: {
content: {
"application/json": components["schemas"]["ErrUnauthorized"];
};
};
/** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
403: {
content: {
"application/json": components["schemas"]["ErrForbidden"];
};
};
/** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
404: {
content: {
"application/json": components["schemas"]["ErrNotFound"];
};
};
/** @description This response is sent when a request conflicts with the current state of the server. */
409: {
content: {
"application/json": components["schemas"]["ErrConflict"];
};
};
/** @description The requested operation cannot be completed because certain conditions were not met. This typically occurs when a required resource state or version check fails. */
412: {
content: {
"application/json": components["schemas"]["ErrPreconditionFailed"];
};
};
/** @description The user has sent too many requests in a given amount of time ("rate limiting") */
429: {
content: {
"application/json": components["schemas"]["ErrTooManyRequests"];
};
};
/** @description The server has encountered a situation it does not know how to handle. */
500: {
content: {
"application/json": components["schemas"]["ErrInternalServerError"];
};
};
};
};
createKey: {
requestBody: {
content: {
"application/json": {
/**
* @description Choose an `API` where this key should be created.
* @example api_123
*/
apiId: string;
/**
* @description To make it easier for your users to understand which product an api key belongs to, you can add prefix them.
*
* For example Stripe famously prefixes their customer ids with cus_ or their api keys with sk_live_.
*
* The underscore is automatically added if you are defining a prefix, for example: "prefix": "abc" will result in a key like abc_xxxxxxxxx
*/
prefix?: string;
/**
* @description The name for your Key. This is not customer facing.
* @example my key
*/
name?: string;
/**
* @description The byte length used to generate your key determines its entropy as well as its length. Higher is better, but keys become longer and more annoying to handle. The default is 16 bytes, or 2^^128 possible combinations.
* @default 16
*/
byteLength?: number;
/**
* @deprecated
* @description Deprecated, use `externalId`
* @example team_123
*/
ownerId?: string;
/**
* @description Your user's Id. This will provide a link between Unkey and your customer record.
* When validating a key, we will return this back to you, so you can clearly identify your user from their api key.
* @example team_123
*/
externalId?: string;
/**
* @description This is a place for dynamic meta data, anything that feels useful for you should go here
* @example {
* "billingTier": "PRO",
* "trialEnds": "2023-06-16T17:16:37.161Z"
* }
*/
meta?: {
[key: string]: unknown;
};
/**
* @description A list of roles that this key should have. If the role does not exist, an error is thrown
* @example [
* "admin",
* "finance"
* ]
*/
roles?: string[];
/**
* @description A list of permissions that this key should have. If the permission does not exist, an error is thrown
* @example [
* "domains.create_record",
* "say_hello"
* ]
*/
permissions?: string[];
/**
* @description You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.
* @example 1623869797161
*/
expires?: number;
/**
* @description You can limit the number of requests a key can make. Once a key reaches 0 remaining requests, it will automatically be disabled and is no longer valid unless you update it.
* @example 1000
*/
remaining?: number;
/**
* @description Unkey enables you to refill verifications for each key at regular intervals.
* @example {
* "interval": "monthly",
* "amount": 100,
* "refillDay": 15
* }
*/
refill?: {
/**
* @description Unkey will automatically refill verifications at the set interval.
* @enum {string}
*/
interval: "daily" | "monthly";
/** @description The number of verifications to refill for each occurrence is determined individually for each key. */
amount: number;
/**
* @description The day of the month, when we will refill the remaining verifications. To refill on the 15th of each month, set 'refillDay': 15.
* If the day does not exist, for example you specified the 30th and it's february, we will refill them on the last day of the month instead.
*/
refillDay?: number;
};
/**
* @description Unkey comes with per-key fixed-window ratelimiting out of the box.
* @example {
* "type": "fast",
* "limit": 10,
* "duration": 60000
* }
*/
ratelimit?: {
/**
* @description Async will return a response immediately, lowering latency at the cost of accuracy. Will be required soon.
* @default true
*/
async?: boolean;
/**
* @deprecated
* @description Deprecated, use `async`. Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.
* @default fast
* @enum {string}
*/
type?: "fast" | "consistent";
/** @description The total amount of requests in a given interval. */
limit: number;
/**
* @description The window duration in milliseconds. Will be required soon.
* @example 60000
*/
duration?: number;
/**
* @deprecated
* @description How many tokens to refill during each refillInterval.
*/
refillRate?: number;
/**
* @deprecated
* @description The refill timeframe, in milliseconds.
*/
refillInterval?: number;
};
/**
* @description Sets if key is enabled or disabled. Disabled keys are not valid.
* @default true
* @example false
*/
enabled?: boolean;
/**
* @description You may want to show keys again later. While we do not recommend this, we leave this option open for you.
*
* In addition to storing the key's hash, recoverable keys are stored in an encrypted vault, allowing you to retrieve and display the plaintext later.
*
* [https://www.unkey.com/docs/security/recovering-keys](https://www.unkey.com/docs/security/recovering-keys) for more information.
* @default false
*/
recoverable?: boolean;
/**
* @description Environments allow you to divide your keyspace.
*
* Some applications like Stripe, Clerk, WorkOS and others have a concept of "live" and "test" keys to
* give the developer a way to develop their own application without the risk of modifying real world
* resources.
*
* When you set an environment, we will return it back to you when validating the key, so you can
* handle it correctly.
*/
environment?: string;
};
};
};
responses: {
/** @description The configuration for an api */
200: {
content: {
"application/json": {
/**
* @description The id of the key. This is not a secret and can be stored as a reference if you wish. You need the keyId to update or delete a key later.
* @example key_123
*/
keyId: string;
/**
* @description The newly created api key, do not store this on your own system but pass it along to your user.
* @example prefix_xxxxxxxxx
*/
key: string;
};
};
};
/** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
400: {
content: {
"application/json": components["schemas"]["ErrBadRequest"];
};
};
/** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
401: {
content: {
"application/json": components["schemas"]["ErrUnauthorized"];
};
};
/** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
403: {
content: {
"application/json": components["schemas"]["ErrForbidden"];
};
};
/** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
404: {
content: {
"application/json": components["schemas"]["ErrNotFound"];
};
};
/** @description This response is sent when a request conflicts with the current state of the server. */
409: {
content: {
"application/json": components["schemas"]["ErrConflict"];
};
};
/** @description The requested operation cannot be completed because certain conditions were not met. This typically occurs when a required resource state or version check fails. */
412: {
content: {
"application/json": components["schemas"]["ErrPreconditionFailed"];
};
};
/** @description The user has sent too many requests in a given amount of time ("rate limiting") */
429: {
content: {
"application/json": components["schemas"]["ErrTooManyRequests"];
};
};
/** @description The server has encountered a situation it does not know how to handle. */
500: {
content: {
"application/json": components["schemas"]["ErrInternalServerError"];
};
};
};
};
verifyKey: {
requestBody: {
content: {
"application/json": components["schemas"]["V1KeysVerifyKeyRequest"];
};
};
responses: {
/** @description The verification result */
200: {
content: {
"application/json": components["schemas"]["V1KeysVerifyKeyResponse"];
};
};
/** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
400: {
content: {
"application/json": components["schemas"]["ErrBadRequest"];
};
};
/** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
401: {
content: {
"application/json": components["schemas"]["ErrUnauthorized"];
};
};
/** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
403: {
content: {
"application/json": components["schemas"]["ErrForbidden"];
};
};
/** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is pro