Access the BIMP API

Find your organization ID, create an API key, and make an authenticated request.

Use the BIMP API when an automation or service needs BIMP access without a browser session. You need the BIMP environment URL, your organization ID, and an API key with permission to perform the requested action.

API access is available only when the organization’s edition or active grant includes the Automation API.

Find your organization ID

Use the organization switcher in the BIMP header to select the organization your automation will access. Then open Settings → Organization → Admin.

The organization details show the value as Org ID. Copy the complete value. You will use it in every organization-scoped API path:

/api/v1/org/<organization-id>/...

The organization ID must match the organization that owns the API key. IDs are opaque, so do not derive them from the organization name or reuse a resource ID from another organization.

Create an API key

Open Settings → Automation → API keys and choose Create API key.

Name the key after the automation and its owner so another administrator can identify its purpose later.

Choose the access model

Select either:

Role, to use a built-in or custom role such as Policy Automation; or
Explicit permissions, to grant only the listed resource actions.

Prefer the smallest access that completes the job. Draft mapping automation does not need policy-publication permission.

Set the expiry

Choose 30, 90, 180, or 365 days, or explicitly select unlimited expiry when your organization accepts that lifecycle.

Prefer an expiry that matches the automation’s expected lifetime. Review long-lived keys regularly.

Store the secret

BIMP shows the complete secret only once after creation. Copy it directly to your secret manager. If you lose the secret, create a replacement key.

Do not store it in a repository, workflow file, policy reason, pull or merge request, provider comment, or build log.

Prepare the request

Set the BIMP environment URL and organization ID:

export BIMP_API_URL="https://<your-bimp-host>"
export BIMP_ORGANIZATION_ID="<organization-id>"

Expose the secret from your secret manager as BIMP_API_KEY. Avoid entering the secret directly into a command that will be retained in shared shell history.

API requests authenticate with the x-api-key header:

x-api-key: <api-key-secret>

Make your first request

List the repositories available to the API key:

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $BIMP_API_KEY" \
  --header "accept: application/json" \
  "$BIMP_API_URL/api/v1/org/$BIMP_ORGANIZATION_ID/repositories"

This request confirms that the environment URL, organization ID, API key, and read permission work together. Follow any returned cursor instead of constructing pagination values.

Find available API operations

Retrieve the current OpenAPI 3.1 contract from the same BIMP environment:

curl --fail-with-body --silent --show-error \
  --header "accept: application/json" \
  "$BIMP_API_URL/api/v1/openapi.json"

Use this runtime document as the source of truth for paths, methods, request and response schemas, and permission metadata. Organization-scoped operations use the organization ID in their path. Validate request bodies before sending them.

Resolve access errors

`401 Unauthorized`

The request did not contain a valid active API key. Confirm the x-api-key header, key expiry, and whether the key was revoked. Create a replacement if the secret is lost.

`403 Forbidden`

The key is valid but its service account lacks authority for the action. Review its role or explicit permissions and grant only the missing resource action.

`404 Not Found`

Confirm that:

the organization ID in the path is the Org ID shown in the selected organization’s Admin settings;
the API key belongs to that organization; and
any resource ID in the path also belongs to that organization.

BIMP can return 404 for a resource outside the key’s organization so the response does not disclose cross-organization data.

Rotate or revoke access

Create a replacement key before changing an active automation, verify the new key, and then revoke the old key from Settings → Automation → API keys.

Revoke a key immediately when its automation, owner, or environment changes, or when the secret may have been exposed. Revocation disables the credential while preserving the metadata needed for audit.