openapi: 3.2.0 info: title: Apiary Authentication API version: '2020-03-02' summary: Apiary loves APIs. Of course then, we have an API too. description: The Apiary API is Apiary.io's own public API. contact: name: Apiary Support email: support@apiary.io url: https://help.apiary.io license: name: Proprietary — Oracle Cloud Infrastructure url: https://apiary.io/tos termsOfService: https://apiary.io/tos x-apiary-description-format: apiblueprint x-apiary-last-updated: '2020-03-02T13:09:52.558Z' x-provenance: generated: '2026-09-02' method: derived source: https://jsapi.apiary.io/apis/apiary source_http_status: 200 source_saved_verbatim: api-description/apiary-api-description.json note: 'Derived from Apiary''s own published API description document, fetched from Apiary''s own host (jsapi.apiary.io) and describing Apiary''s own production host (https://api.apiary.io/). Ownership is unambiguous: the description names itself "Apiary API", is owned by the Apiary account, declares production base https://api.apiary.io/, and lists support@apiary.io. Apiary publishes no OpenAPI/Swagger of its own — /openapi.json, /openapi.yaml, /swagger.json, /api-docs, /docs and /redoc all return 404 on api.apiary.io (probed 2026-09-02) — so this document is a translation, not a harvest.' servers: - url: https://api.apiary.io description: Production tags: - name: Authentication description: Apiary API uses Bearer Token Authorization (RFC 6750). Tokens are managed at https://login.apiary.io/tokens, or created, listed and deleted over this resource using Basic Authentication. This collection works only for users who are not part of IDCS-controlled teams. externalDocs: url: https://login.apiary.io/tokens paths: /authorization: post: operationId: createAuthorizationToken summary: Create an Authorization Token description: Create a new authorization token for an authenticated user. This authorization token may be used to access protected resources. Pass `tokenRegenerate=true` to regenerate a token that already exists under the same description. tags: - Authentication security: - basicAuth: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - tokenDescription properties: tokenDescription: type: string maxLength: 30 description: A string, 30 characters or less, describing the token. tokenRegenerate: type: boolean default: false description: Regenerate the token if one already exists with this description. example: tokenDescription: What's this token for? tokenRegenerate: false responses: '201': description: Token created (or regenerated). headers: Location: description: URL of the newly created token resource. schema: type: string format: uri content: application/json: schema: $ref: '#/components/schemas/Token' '400': description: Token Description Missing, Token Description Length Greater Than 30, or Token Description Already Exists. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Transport Layer Security Required. content: application/json: schema: $ref: '#/components/schemas/Error' get: operationId: listAuthorizationTokens summary: Get Existing Authorization Tokens description: Get existing authorization tokens for an authenticated user. Token values themselves are not returned — only their descriptions and resource URLs. tags: - Authentication security: - basicAuth: [] responses: '200': description: The caller's token list. content: application/json: schema: $ref: '#/components/schemas/TokenList' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Transport Layer Security Required. content: application/json: schema: $ref: '#/components/schemas/Error' delete: operationId: deleteAuthorizationToken summary: Delete an Existing Authorization Token description: Delete an existing authorization token for an authenticated user. The token may no longer be used to access protected resources. The token to delete is identified by its description, either form-encoded in the body or percent-encoded as a path segment on the token URL. tags: - Authentication security: - basicAuth: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - tokenDescription properties: tokenDescription: type: string maxLength: 30 description: The description identifying the token to delete. example: tokenDescription: What's this token for? responses: '204': description: Token deleted. No content. '400': description: Token Description Missing, or Token Description Length Greater Than 30. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Transport Layer Security Required. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object description: The Apiary API error envelope — a single `error` string drawn from a closed enum. properties: error: type: string description: An error message. enum: - Unauthorized - Transport Layer Security Required - Token Invalid - Token Description Length Greater Than 30 - Token Description Missing - Token Description Already Exists - Token Creation Failed - Token Deletion Failed - Token Retrieval Failed - User Query Failed - API Query Failed - Team ID Invalid TokenList: type: object properties: tokens: type: array description: A list of Tokens. items: $ref: '#/components/schemas/Token' Token: type: object properties: token: type: string description: A string granting a user authorization to protected resources. tokenDescription: type: string maxLength: 30 description: A string, 30 characters or less, describing the token. tokenUrl: type: string format: uri description: A URL string representing a token resource. securitySchemes: basicAuth: type: http scheme: basic description: HTTP Basic authentication with the Apiary account email and password. Used only on /authorization to mint, list and revoke tokens. Not available to users in IDCS-controlled teams. bearerAuth: type: http scheme: bearer description: 'RFC 6750 Bearer token. Generate at https://login.apiary.io/tokens or via POST /authorization. Sent as `Authorization: Bearer `.' legacyToken: type: apiKey in: header name: Authentication description: 'Legacy Apiary token header, sent as `Authentication: Token ` (note: the header is `Authentication`, not `Authorization`). Apiary labels the /blueprint/* group legacy. This is the same token value the Apiary CLI reads from the APIARY_API_KEY environment variable.' externalDocs: description: Apiary API interactive documentation (Apiary-hosted) url: https://apiary.docs.apiary.io