Management API reference

Every operation under https://app.endpointblank.com/api/v1, drawn from the same OpenAPI document you can load into your own tools. Authenticate with a management API key as Authorization: Bearer epb_mk_...; the guide covers keys, paging, retries and rate limits.

Organization

GET /organization

The organization this key belongs to

Responses

  • 200 The organization and the key used
  • 401 Missing, invalid or revoked key
  • 429 Rate limited

API packages

GET /api_packages

List API packages

Parameters

limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of API packages
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 429 Rate limited

POST /api_packages

Create an API package

Parameters

Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

name required string

Responses

  • 201 The API package
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 422 Invalid fields, or the name is taken
  • 429 Rate limited

GET /api_packages/{id}

Get an API package

Parameters

id required uuid (path)

Responses

  • 200 The API package
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

PATCH /api_packages/{id}

Rename an API package

Parameters

id required uuid (path)

JSON body

name required string

Responses

  • 200 The API package
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Invalid fields, or the name is taken
  • 429 Rate limited

DELETE /api_packages/{id}

Delete an API package

Refused with api_package_assigned while a client holds it.

Parameters

id required uuid (path)

Responses

  • 200 Deleted
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 The package is assigned to clients
  • 429 Rate limited

GET /api_packages/{id}/endpoints

List what an API package publishes

Parameters

id required uuid (path)
limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of the package's endpoints
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 404 Package not found
  • 429 Rate limited

POST /api_packages/{id}/endpoints

Add an endpoint to an API package

Derives the grants of every client holding the package and pushes them to the provider's intake.

Parameters

id required uuid (path)
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

application_id required uuid
environment_id required uuid
endpoint_id uuid or null Omit or null for every endpoint of the application.

Responses

  • 201 The endpoint was added
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Package not found
  • 422 Invalid fields, an id that does not exist, or already in the package
  • 429 Rate limited

DELETE /api_packages/{id}/endpoints/{access_id}

Remove an endpoint from an API package

Revokes every client grant the entry was the only reason for, on the provider's intake.

Parameters

id required uuid (path)
access_id required uuid (path)

Responses

  • 200 Deleted
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 429 Rate limited

Endpoints

GET /endpoints

List the organization's endpoints

Parameters

application_id uuid (query) Only this application's endpoints.
version string (query) Only endpoints deployed in an application version of this name. Without application_id this matches the name in every application of the organization; combine it with application_id for one application's version.
limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of endpoints
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 422 application_id is not a UUID, or version is not a string
  • 429 Rate limited

Applications

GET /applications

List applications

Parameters

limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of applications
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 429 Rate limited

POST /applications

Create an application

Places the application in each environment given a base URL; at least one is required.

Parameters

Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

environment_base_urls required object Environment id to base URL, e.g. https://api.example.com
name required string
organization_group_id uuid
public boolean

Responses

  • 201 The created application
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 422 Invalid fields, or intake refused the application
  • 429 Rate limited

GET /applications/{application_id}/environments

List the environments an application runs in

Parameters

application_id required string (path)
limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of application environments
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

POST /applications/{application_id}/environments

Place an application in an environment at a base URL

Parameters

application_id required string (path)
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

base_url required string
environment_id required uuid

Responses

  • 201 The application environment
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Application not found
  • 422 Invalid fields, or intake refused the environment
  • 429 Rate limited

DELETE /applications/{application_id}/environments/{id}

Remove an application from an environment

Refused (has_dependents) while access grants on the application in that environment, or credentials bound to it, depend on it.

Parameters

application_id required string (path)
id required string (path)

Responses

  • 200 The application left the environment
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Still in use, or intake refused the removal
  • 429 Rate limited

GET /applications/{id}

Get an application

Parameters

id required string (path)

Responses

  • 200 The application
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

PATCH /applications/{id}

Rename an application or change whether it is public

Parameters

id required string (path)

JSON body

name string
public boolean

Responses

  • 200 The updated application
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Invalid fields, or intake refused the change
  • 429 Rate limited

DELETE /applications/{id}

Delete an application

Refused (has_dependents) while access grants or credentials depend on it.

Parameters

id required string (path)

Responses

  • 200 The application was deleted
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Still in use, or intake refused the delete
  • 429 Rate limited

Environments

GET /environments

List environments

Parameters

limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of environments
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 429 Rate limited

POST /environments

Create an environment

Parameters

Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

domain required string
name required string
is_default boolean

Responses

  • 201 The created environment
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 422 Invalid fields, or intake refused the environment
  • 429 Rate limited

GET /environments/{id}

Get an environment

Parameters

id required string (path)

Responses

  • 200 The environment
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

PATCH /environments/{id}

Update an environment

The production environment can't be changed (protected).

Parameters

id required string (path)

JSON body

domain string
is_default boolean
name string

Responses

  • 200 The updated environment
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Invalid fields, protected, or intake refused the change
  • 429 Rate limited

DELETE /environments/{id}

Delete an environment

Refused while access grants are scoped to it or credentials are bound to an application in it. The production environment can't be deleted.

Parameters

id required string (path)

Responses

  • 200 The environment was deleted
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Protected, still in use, or intake refused the delete
  • 429 Rate limited

Credentials

GET /credentials

List runtime client credentials (metadata only, never a secret)

Parameters

limit integer (query)
after string (query) The next_cursor from the previous page.
application_environment_id uuid (query) Only credentials for this application environment. An id that is not a UUID matches nothing and answers an empty page, not 400.

Responses

  • 200 A page of credentials and the next cursor
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 429 Rate limited

POST /credentials

Issue a credential for one of your application environments

The secret is in this answer and nowhere else. It is never stored for Idempotency-Key replay: a retry with the same key answers 409 idempotency_replay_unavailable instead, with the credential's location header. An error answer holds no secret and is replayed as usual.

Parameters

Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

application_environment_id required uuid

Responses

  • 201 The credential, with client_secret shown once
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 No such application environment in this organization
  • 409 Idempotency-Key already used; the answer can't be replayed
  • 422 Invalid fields, or intake refused the credential
  • 429 Rate limited
  • 503 Intake unreachable; nothing was created

GET /credentials/{id}

A runtime client credential (metadata only)

Parameters

id required uuid (path)

Responses

  • 200 The credential
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

DELETE /credentials/{id}

Revoke a credential

Removes it from intake, then deletes it. Its current and previous secrets stop authenticating.

Parameters

id required uuid (path)

Responses

  • 200 Revoked
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 409 An intake's own credential (intake_credential); nothing was revoked
  • 422 Intake refused the delete (intake_rejected; the revoke is queued, and the credential stops authenticating once intake takes it. It is still listed here until a retried DELETE succeeds.), or intake revoked it but the record could not be removed here (delete_refused; retry the DELETE)
  • 429 Rate limited
  • 503 Intake was not reached; the revoke is queued, and the credential stops authenticating once intake takes it. It is still listed here until a retried DELETE succeeds.

POST /credentials/{id}/rotate

Issue a new secret; the old one works for the grace window

The secret is in this answer and nowhere else. It is never stored for Idempotency-Key replay: a retry with the same key answers 409 idempotency_replay_unavailable instead, with the credential's location header. An error answer holds no secret and is replayed as usual. Only one previous secret is kept: rotating again ends the earlier secret's grace window immediately, so recover a lost answer by reading the credential, not by rotating again. Concurrent rotations of one credential race: only one of the secrets returned will work.

Parameters

id required uuid (path)
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

Responses

  • 200 The credential, with the new client_secret shown once
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 409 Idempotency-Key already used; the answer can't be replayed (idempotency_replay_unavailable), or an intake's own credential (intake_credential); nothing was rotated
  • 422 Intake refused the new secret
  • 429 Rate limited
  • 503 Intake unreachable; the secret was not rotated

Client packages

GET /clients/{client_id}/packages

List the API packages a client holds

For a client that has not accepted its invite, the packages set up for it to get when it does (status pending).

Parameters

client_id required uuid (path) A client's id (from GET /clients).
limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of assignments
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 404 No such client
  • 429 Rate limited

POST /clients/{client_id}/packages

Assign an API package to a client

Grants the client every endpoint the package publishes in environment_id, pushed to your intake. For a client that has not accepted its invite, sets the package up (status pending) to be assigned, and pushed, the moment it accepts; one that cannot be assigned then is kept as status refused with the reason, and your administrators are emailed. Refused (422) when the client already holds or is set up for the package (already_assigned) or the package publishes nothing in that environment (nothing_published_in_environment).

Parameters

client_id required uuid (path) A client's id (from GET /clients).
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

api_package_id required uuid
environment_id required uuid

Responses

  • 201 The assignment
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 No such client
  • 422 Refused: environment_not_found, api_package_not_found, already_assigned, nothing_published_in_environment or validation_failed
  • 429 Rate limited

PATCH /clients/{client_id}/packages/{id}

Change the environment a client holds an API package in

Re-derives the client's grants from the package in the new environment, or moves a pending one. Refused (422) with nothing_published_in_environment when the package publishes nothing there, or (client_accepted) when the client accepted while this was sent.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required uuid (path) A package assignment's id.

JSON body

environment_id required uuid

Responses

  • 200 The assignment
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 Not found
  • 422 Refused: environment_not_found, nothing_published_in_environment, client_accepted (a pending assignment, and the client accepted while this was sent) or validation_failed
  • 429 Rate limited

DELETE /clients/{client_id}/packages/{id}

Un-assign an API package from a client

Revokes every grant the package was the client's last reason for. A grant also granted directly or by another package stays. Drops a pending one, or dismisses one refused on accept.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required uuid (path) A package assignment's id.

Responses

  • 200 The package was un-assigned
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 Not found
  • 422 Refused: client_accepted (a pending assignment, and the client accepted while this was sent, so it is being applied)
  • 429 Rate limited

Client grants

GET /clients/{client_id}/grants

List the grants a client holds directly

Grants derived from API packages are not listed here unless they were also granted directly. For a client that has not accepted its invite, the grants set up for it to get when it does (status pending).

Parameters

client_id required uuid (path) A client's id (from GET /clients).
limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of direct grants
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 404 No such client
  • 429 Rate limited

POST /clients/{client_id}/grants

Grant a client access to an application or endpoint

Grants the whole client organization access to one endpoint of your application, or to every endpoint when target_endpoint_id is omitted, in one environment the application is deployed to. Pushed to your intake. For a client that has not accepted its invite, sets the grant up (status pending) to be made, and pushed, the moment it accepts; one that cannot be made then is kept as status refused with the reason, and your administrators are emailed.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

environment_id required uuid
target_application_id required uuid
target_endpoint_id uuid or null

Responses

  • 201 The grant
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 No such client
  • 409 grant_revoked_concurrently: the grant was made, then revoked by another request before it could be returned
  • 422 Refused: application_not_found, endpoint_not_found, environment_not_in_application, already_granted or validation_failed
  • 429 Rate limited

DELETE /clients/{client_id}/grants/{id}

Revoke a client's direct grant

Revokes the grant unless an API package the client holds also derives it; still_granted_by_package then says the client keeps it through the package. Drops a pending one, or dismisses one refused on accept.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required uuid (path) A direct grant's id.

Responses

  • 200 The direct grant was removed
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 Not found
  • 422 Refused: client_accepted (a pending grant, and the client accepted while this was sent, so it is being applied)
  • 429 Rate limited

Managed clients

GET /clients/{client_id}/applications

Managed client: List applications

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of applications
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 429 Rate limited

POST /clients/{client_id}/applications

Managed client: Create an application

Places the application in each environment given a base URL; at least one is required. Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

environment_base_urls required object Environment id to base URL, e.g. https://api.example.com
name required string
organization_group_id uuid
public boolean

Responses

  • 201 The created application
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 422 Invalid fields, or intake refused the application
  • 429 Rate limited

GET /clients/{client_id}/applications/{application_id}/environments

Managed client: List the environments an application runs in

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
application_id required string (path)
limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of application environments
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

POST /clients/{client_id}/applications/{application_id}/environments

Managed client: Place an application in an environment at a base URL

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
application_id required string (path)
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

base_url required string
environment_id required uuid

Responses

  • 201 The application environment
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Application not found
  • 422 Invalid fields, or intake refused the environment
  • 429 Rate limited

DELETE /clients/{client_id}/applications/{application_id}/environments/{id}

Managed client: Remove an application from an environment

Refused (has_dependents) while access grants on the application in that environment, or credentials bound to it, depend on it. Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
application_id required string (path)
id required string (path)

Responses

  • 200 The application left the environment
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Still in use, or intake refused the removal
  • 429 Rate limited

GET /clients/{client_id}/applications/{id}

Managed client: Get an application

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required string (path)

Responses

  • 200 The application
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

PATCH /clients/{client_id}/applications/{id}

Managed client: Rename an application or change whether it is public

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required string (path)

JSON body

name string
public boolean

Responses

  • 200 The updated application
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Invalid fields, or intake refused the change
  • 429 Rate limited

DELETE /clients/{client_id}/applications/{id}

Managed client: Delete an application

Refused (has_dependents) while access grants or credentials depend on it. Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required string (path)

Responses

  • 200 The application was deleted
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Still in use, or intake refused the delete
  • 429 Rate limited

GET /clients/{client_id}/credentials

Managed client: List runtime client credentials (metadata only, never a secret)

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
limit integer (query)
after string (query) The next_cursor from the previous page.
application_environment_id uuid (query) Only credentials for this application environment. An id that is not a UUID matches nothing and answers an empty page, not 400.

Responses

  • 200 A page of credentials and the next cursor
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 429 Rate limited

POST /clients/{client_id}/credentials

Managed client: Issue a credential for one of your application environments

The secret is in this answer and nowhere else. It is never stored for Idempotency-Key replay: a retry with the same key answers 409 idempotency_replay_unavailable instead, with the credential's location header. An error answer holds no secret and is replayed as usual. Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

application_environment_id required uuid

Responses

  • 201 The credential, with client_secret shown once
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 No such application environment in this organization
  • 409 Idempotency-Key already used; the answer can't be replayed
  • 422 Invalid fields, or intake refused the credential
  • 429 Rate limited
  • 503 Intake unreachable; nothing was created

GET /clients/{client_id}/credentials/{id}

Managed client: A runtime client credential (metadata only)

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required uuid (path)

Responses

  • 200 The credential
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

DELETE /clients/{client_id}/credentials/{id}

Managed client: Revoke a credential

Removes it from intake, then deletes it. Its current and previous secrets stop authenticating. Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required uuid (path)

Responses

  • 200 Revoked
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 409 An intake's own credential (intake_credential); nothing was revoked
  • 422 Intake refused the delete (intake_rejected; the revoke is queued, and the credential stops authenticating once intake takes it. It is still listed here until a retried DELETE succeeds.), or intake revoked it but the record could not be removed here (delete_refused; retry the DELETE)
  • 429 Rate limited
  • 503 Intake was not reached; the revoke is queued, and the credential stops authenticating once intake takes it. It is still listed here until a retried DELETE succeeds.

POST /clients/{client_id}/credentials/{id}/rotate

Managed client: Issue a new secret; the old one works for the grace window

The secret is in this answer and nowhere else. It is never stored for Idempotency-Key replay: a retry with the same key answers 409 idempotency_replay_unavailable instead, with the credential's location header. An error answer holds no secret and is replayed as usual. Only one previous secret is kept: rotating again ends the earlier secret's grace window immediately, so recover a lost answer by reading the credential, not by rotating again. Concurrent rotations of one credential race: only one of the secrets returned will work. Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required uuid (path)
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

Responses

  • 200 The credential, with the new client_secret shown once
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 409 Idempotency-Key already used; the answer can't be replayed (idempotency_replay_unavailable), or an intake's own credential (intake_credential); nothing was rotated
  • 422 Intake refused the new secret
  • 429 Rate limited
  • 503 Intake unreachable; the secret was not rotated

GET /clients/{client_id}/environments

Managed client: List environments

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of environments
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 429 Rate limited

POST /clients/{client_id}/environments

Managed client: Create an environment

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

domain required string
name required string
is_default boolean

Responses

  • 201 The created environment
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 422 Invalid fields, or intake refused the environment
  • 429 Rate limited

GET /clients/{client_id}/environments/{id}

Managed client: Get an environment

Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required string (path)

Responses

  • 200 The environment
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

PATCH /clients/{client_id}/environments/{id}

Managed client: Update an environment

The production environment can't be changed (protected). Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required string (path)

JSON body

domain string
is_default boolean
name string

Responses

  • 200 The updated environment
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Invalid fields, protected, or intake refused the change
  • 429 Rate limited

DELETE /clients/{client_id}/environments/{id}

Managed client: Delete an environment

Refused while access grants are scoped to it or credentials are bound to an application in it. The production environment can't be deleted. Acts on your managed client's organization, only while the client is unclaimed; otherwise 404. A credential's secret is pushed only to the intake the client's organization is on.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
id required string (path)

Responses

  • 200 The environment was deleted
  • 401 Missing, invalid or revoked key
  • 403 Read-only key
  • 404 Not found
  • 422 Protected, still in use, or intake refused the delete
  • 429 Rate limited

Clients

GET /clients

List clients (client invites, pending and accepted)

Parameters

limit integer (query)
after string (query) The next_cursor from the previous page.

Responses

  • 200 A page of clients
  • 400 Invalid pagination
  • 401 Missing, invalid or revoked key
  • 429 Rate limited

POST /clients

Invite a client

Creates a client invite, as the portal's Invite Client form does. Counts against the plan's client limit. Without email, share the returned invite_code with the client; it accepts the invite from its own EndPointBlank organization. With email, the invite is for that address: an administrator of the client's organization whose confirmed email it is accepts it in EndPointBlank, and signup_url (in this answer only) is a link you send them yourself, since EndPointBlank sends no invite email. Signing up from it links their new organization. The answer is the same whether or not the address has an account. With managed: true, email is your customer's address. When it belongs to an EndPointBlank user, no managed client is created: that user is invited to the account they already have instead. Nothing is emailed and there is no signup_url; they accept or decline on their Providers page, and the invite never expires (invite_expires_at is null). The answer is that invite, with managed: false and invite_status pending, so stop provisioning; it is a client like any accepted invite once they accept. Otherwise the managed client is created as without email. packages and grants set up what the client gets when it accepts: they are assigned and granted, and pushed to your intake, as soon as it does, with nothing more for you to do. Each is checked as POST /clients/{client_id}/packages and /grants check it, and a refused one refuses the whole request.

Parameters

Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

name required string
contacts array of object Your contacts to share with the client. An existing contact with the same email (in any case) is reused. Listing one email twice is refused with invalid_contacts.
contacts[].email required string
contacts[].first_name required string
contacts[].last_name required string
contacts[].id uuid
contacts[].phone_number string or null
contacts[].title string or null
email email or null Invite by email address instead of a code. At most one unanswered invite per address (already_invited), and a daily limit (invite_rate_limited). The sign-up link works for 14 days. With managed: true, your customer's address: if it belongs to an EndPointBlank user they are invited instead (managed: false, no signup_url, never expires), with the same already_invited and invite_rate_limited refusals; otherwise it creates the managed client.
grants array of object Direct grants to make when the client accepts. Not with managed: true (invalid_managed); grant them afterwards with POST /clients/{client_id}/grants.
grants[].environment_id required uuid
grants[].target_application_id required uuid
grants[].target_endpoint_id uuid or null
managed boolean Create the client's organization now and run it for your customer: no invite to accept, no users, set up under /clients/{client_id}/... until the customer claims it. With an email that belongs to an EndPointBlank user, invites that user instead: check managed in the answer. Default false.
owner_email email or null With managed: true only (invalid_managed otherwise): your customer's address. They sign in to EndPointBlank with a one-time code sent to it to approve an AI agent for the managed client, without claiming it. Stored only when this request creates a managed client; replace it with PATCH /clients/{id}.
packages array of object API packages to assign when the client accepts. Not with managed: true (invalid_managed); assign them afterwards with POST /clients/{client_id}/packages.
packages[].api_package_id required uuid
packages[].environment_id required uuid

Responses

  • 201 The new client: a managed client (managed: true), or, for managed: true with an existing user's email, a pending invite to that user (managed: false)
  • 401 Missing, invalid or revoked key
  • 402 The plan's client limit is reached
  • 403 The key is read-only
  • 409 already_invited: the address has an invite from you nobody has answered; or idempotency_replay_unavailable on a retry of an email invite, whose signup_url is not replayed
  • 422 Refused: validation_failed (a blank name, an invalid contact or an invalid grant), invalid_contacts (contacts is not a list of objects, or lists one email twice), invalid_packages or invalid_grants (not a list of objects), a package or grant refusal (see the error code), invalid_managed (also when packages or grants come with managed: true), or intake_rejected (intake refused a managed client's organization)
  • 429 invite_rate_limited: the day's email invites are used up; Retry-After says when the next one can be made
  • 503 Intake unreachable; nothing was created

POST /clients/{client_id}/claim_invites

Invite your customer to claim a managed client

Emails an invite to join the client's organization. The first person to accept claims it: it becomes an ordinary client with its own users, every credential you issued for it is rotated (the old secrets keep working for the grace window), and from then on its applications, environments and credentials answer 404 to your key. Sending again to the same address resends the invite. Pass `return_to` to have the customer's browser sent back to you once accepting has claimed the client, the way an OAuth redirect_uri works: it must equal, byte for byte, one of the claim return URLs your organization's admins registered on the management API keys page (https, or http on a loopback host; no fragment). It is checked again when the customer is redirected, so removing a URL stops it being used by invites already sent; they land on EndPointBlank instead. A resend replaces the invite's return_to, with none when the resend names none; a resend from your client's page in EndPointBlank keeps it. An empty `return_to` ("") is not treated as absent: it answers 422 return_to_not_registered. An invite to an organization that was already claimed, or an acceptance that did not claim it, never redirects.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

email required email
return_to uri Where to send the customer once they have claimed the client. Must exactly equal one of your registered claim return URLs; omit it for none (an empty string is refused, not treated as absent).

Responses

  • 201 The invite was sent
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 Not found
  • 422 Not an unclaimed managed client of yours, an invalid email, a return_to that is not one of your claim return URLs, the empty string included (return_to_not_registered), or a client whose removal has started (client_being_removed): send DELETE /clients/{id} again to finish it
  • 429 Rate limited

DELETE /clients/{client_id}/invite

Revoke a client's invite

Revokes an invite the client has not accepted, code or email, pending, declined or expired. The invite is deleted with anything set up for it to get on accept, and its sign-up link stops working. Safe to retry: a revoked invite answers 404. An accepted client is removed with DELETE /clients/{id}.

Parameters

client_id required uuid (path) A client's id.

Responses

  • 200 The invite was revoked
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 Not found
  • 422 invite_accepted: the client has accepted (a managed client always has); remove it with DELETE /clients/{id} instead
  • 429 Rate limited

POST /clients/{client_id}/portal_sessions

Open your customer's managed account portal

Answers a URL that signs your customer in to the portal of the managed account you run for them, where they see and revoke the AI agents connected to it, without an EndPointBlank login or an emailed code (which keeps working too). Like Stripe's billing portal sessions: call it when the customer clicks through in your app and redirect their browser to `url` straight away. The URL works once and expires 60 seconds after it is created (`expires_at`); an expired or used one shows a page asking the customer to go back to your app. The sign-in it gives lasts 30 minutes and ends at once if the client is claimed or its owner_email changes. Only for an unclaimed managed client of yours whose removal has not started and that has an owner_email (set it with PATCH /clients/{id}); the customer is signed in as that address. The portal shows no link back to your app and no Sign out: the customer stays in your app for both. An optional `return_url` is checked and echoed back: it must equal, byte for byte, one of the claim return URLs your organization's admins registered on the management API keys page. An empty `return_url` ("") is refused, not treated as absent. The answer is never stored for an Idempotency-Key replay: a retry with the same key answers 409 idempotency_replay_unavailable. Create another session instead.

Parameters

client_id required uuid (path) A client's id (from GET /clients).
Idempotency-Key string (header) Retrying a POST with the same key replays the first answer.

JSON body

return_url uri Checked and echoed back; the portal does not link to it. Must exactly equal one of your registered claim return URLs; omit it for none.

Responses

  • 201 The portal session
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 Not found
  • 409 An Idempotency-Key retry: the URL is never replayed
  • 422 Not an unclaimed managed client of yours (client_not_managed), one whose removal has started (client_being_removed), one with no owner_email (owner_email_missing), or a return_url that is not one of your claim return URLs, the empty string included (return_url_not_registered)
  • 429 Rate limited

GET /clients/{id}

Get a client

Parameters

id required uuid (path) A client's id.

Responses

  • 200 The client
  • 401 Missing, invalid or revoked key
  • 404 Not found
  • 429 Rate limited

PATCH /clients/{id}

Set a managed client's owner email

Sets or replaces owner_email on your managed client while it is unclaimed: the address your customer gets a one-time sign-in code at to approve an AI agent for it. A replaced address can no longer sign in, a sign-in it already made ends, and every AI agent it approved is revoked, at EndPointBlank and at intake; the new owner connects their own. Setting the address the client already has changes nothing. Nothing else is changed here.

Parameters

id required uuid (path) A client's id.

JSON body

owner_email required email

Responses

  • 200 The client
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 Not found
  • 422 validation_failed (owner_email missing or invalid), or client_not_managed (not your managed client, or already claimed)
  • 429 Rate limited

DELETE /clients/{id}

Remove a client

Deletes the invite. When it was your last accepted invite for that client organization, also un-assigns every API package the client holds from you and revokes every grant those packages and direct grants gave it; while another accepted invite links you to the same organization, its packages and grants stay. The revoke is run again a few minutes later, so an assignment or grant made while it ran is taken away too. Safe to retry: a client already removed answers 404 and nothing changes. Anything set up for a pending invite to get on accept is deleted with it. An unclaimed managed client is deleted with everything it holds: its applications with their environments and endpoints, its links to you, its pending claim invites, and its organization. Revoke its credentials first (managed_client_has_credentials otherwise). It is refused, changing nothing, while it holds what this does not remove (client_not_removable: message says what), and with client_not_managed if your customer claimed it before. The first step closes it to claims for good: no claim invite can be sent or accepted after it. A removal that stops partway (intake refusing a step: client_not_removable; intake unreachable or failing with a 5xx: intake_unavailable; any other answer from intake: intake_rejected) leaves what it removed removed and the client still here, and the same DELETE carries it on. While it is partway, its claim invites answer client_being_removed.

Parameters

id required uuid (path) A client's id.

Responses

  • 200 The client was removed
  • 401 Missing, invalid or revoked key
  • 403 The key is read-only
  • 404 Not found
  • 422 An unclaimed managed client that still has credentials, holds what removing it does not remove, or was claimed; or a removal intake refused partway, or answered unexpectedly (intake_rejected)
  • 429 Rate limited
  • 503 Intake could not be reached, or failed (5xx), partway; send the DELETE again

Error codes

Every error is {"error": {"code", "message", "details"}}. Match on code; message is for people and may change. Send Accept: application/json so errors raised before routing also come back as JSON.

Authentication and limits

missing_key 401 No Authorization: Bearer header was sent.
invalid_key 401 The key is unknown, revoked or malformed.
runtime_credential_refused 401 Basic runtime credentials were sent. Send a management API key (epb_mk_...) as a Bearer token.
insufficient_scope 403 The key is read-only and the request writes.
audit_unavailable 503 The write could not be recorded in the audit log, so it was not made. Retry.
rate_limited 429 Too many requests. Wait for the Retry-After header's seconds.
plan_limit 402 Your plan's limit for this resource is reached.

Requests

validation_failed 422 One or more fields are invalid. details lists them by field.
not_found 404 No such resource in your organization, or no such /api/v1 path. Another organization's id answers this too.
invalid_pagination 400 limit is not 1-100, or after is not a next_cursor from an earlier page.
invalid_filter 422 A list filter has the wrong type, such as a non-UUID id.
invalid_idempotency_key 400 The Idempotency-Key header is empty or longer than 255 characters.
idempotency_key_reused 422 The Idempotency-Key was already used for a different request.
idempotency_request_in_progress 409 The first request with this Idempotency-Key is still running. Retry shortly.
idempotency_replay_unavailable 409 The first answer for this Idempotency-Key held a secret shown only once, so it can't be replayed. Read the resource instead.
bad_request 400 The request could not be read, such as a body that isn't valid JSON. Raised before routing.
internal_server_error 500 Something failed on our side. Safe to retry a GET.

Applications, environments and API packages

has_dependents 422 The application or environment still has grants or credentials. Remove them first.
protected 422 The production environment can't be changed or deleted.
invalid_environment_base_urls 422 environment_base_urls must map environment ids to base URLs.
api_package_assigned 422 The API package is still assigned to clients. Remove its assignments first.
intake_sync_failed 422 Intake would not take the change, so nothing was changed. message says why.

Credentials

delete_refused 422 Intake revoked the credential but its record could not be removed here. Retry the DELETE.
intake_credential 409 The credential belongs to an intake and can't be rotated or revoked here.
intake_rejected 422 On a credential, or on creating a managed client: intake refused the change, so nothing was changed. On DELETE /clients/{id}: intake answered a step of removing a managed client unexpectedly, the steps before it stay done, and sending the DELETE again carries it on.
intake_unavailable 503 Intake could not be reached or failed. Nothing was changed, except on DELETE /clients/{id}, where the steps of removing a managed client before it stay done. Retry.

Clients, packages and grants

invalid_contacts 422 contacts must be a list of objects with email, first_name and last_name, each email once.
invalid_packages 422 packages must be a list of objects with api_package_id and environment_id.
invalid_grants 422 grants must be a list of objects with target_application_id and environment_id.
invalid_managed 422 managed is not a boolean, managed: true came with packages or grants (assign those after creating the client), or owner_email came without managed: true.
already_invited 409 That address already has an invite from you that nobody has answered. Make a new link or revoke it.
invite_rate_limited 429 The organization has created as many email invites as it can in a day. Try again later.
not_an_email_invite 422 The client was invited with a code, or to an EndPointBlank account it already has, so it has no sign-up link.
invite_not_open 422 The email invite was accepted or declined, so it has no sign-up link.
invite_accepted 422 The client accepted its invite, so there is nothing to revoke. Remove the client instead.
client_not_accepted 422 The client hasn't accepted its invite yet, so nothing can be assigned or granted.
client_accepted 422 The client just accepted its invite and its setup is being applied. Nothing was changed.
client_not_managed 422 The client is not your managed client, or it was claimed.
client_being_removed 422 The managed client's removal started and stopped partway, so it can't be claimed or removed another way. Send DELETE /clients/{id} again to finish it.
already_a_member 422 That email address already belongs to the client.
return_to_not_registered 422 return_to is not exactly one of your organization's claim return URLs. Register it first.
return_url_not_registered 422 A portal session's return_url is not exactly one of your organization's claim return URLs. Register it first.
owner_email_missing 422 The managed client has no owner_email, so a portal session has nobody to sign in. Set one with PATCH /clients/{id}.
managed_client_has_credentials 422 The managed client still has credentials. Revoke them before removing it.
client_not_removable 422 The managed client holds something removing it does not remove, or intake refused a step of removing it. message says which; after a step, send the DELETE again once it is resolved.
api_package_not_found 422 api_package_id is not one of your API packages.
environment_not_found 422 environment_id is not one of your environments.
already_assigned 422 The client already holds that API package. Change its environment with PATCH.
nothing_published_in_environment 422 The package would give the client no grants in that environment. details lists why.
application_not_found 422 target_application_id is not one of your applications.
endpoint_not_found 422 target_endpoint_id is not an endpoint of target_application_id.
environment_not_in_application 422 environment_id is not one of the target application's environments.
already_granted 422 The client already holds that grant directly.
grant_revoked_concurrently 409 The grant was made, then revoked by another request. List the client's grants to see where it stands.