Integration API
The integration API (/api/v2) is used by CI/CD pipelines and tooling to interact with bifrost, for example to
upload SBOMs or generate security profiles.
See the OpenAPI specification for all endpoints.
Every request is authenticated with a bearer token in the Authorization header:
Authorization: Bearer <token>Two kinds of tokens are accepted:
- API token: a long-lived token created in the bifrost portal and stored as a secret in your CI/CD system.
- Access token: a short-lived token obtained by exchanging a GitHub Actions OIDC token. Nothing to store, nothing to rotate.
API token
Section titled “API token”API tokens are created per organization in the bifrost portal under Settings → API access tokens. The token value is only shown once, store it as a secret in your CI/CD system (for example a GitHub Actions secret). Tokens can be revoked and deleted from the same page, and all changes are recorded in the organization audit log.
curl -X POST "https://portal.bifrostsec.com/api/v2/service/my-service/version/1.2.3/profile" \ -H "Authorization: Bearer $BIFROST_API_TOKEN"GitHub Actions OIDC token exchange
Section titled “GitHub Actions OIDC token exchange”GitHub Actions can issue a short-lived OpenID Connect (OIDC) token that identifies the workflow run: the repository, its owner, the branch and more. bifrost exchanges such a token for an access token valid for 10 minutes, following OAuth 2.0 Token Exchange (RFC 8693). This removes the need to store a long-lived API token as a secret in your repositories.
Two things tie the exchange to your organization:
- The GitHub organization (or user account) owning the repository must be authorized in your bifrost organization.
- The OIDC token must be requested with your bifrost organization id as audience, proving the workflow intends to act on your organization.
Authorize your GitHub organization
Section titled “Authorize your GitHub organization”- Open your organization in the bifrost portal and go to the GitHub card under Settings.
- Click Add GitHub Organization and enter the GitHub organization (or user) name that owns your repositories, for example
bifrostsec. - Note your bifrost organization id displayed in the same card. It is also part of the portal URL,
https://portal.bifrostsec.com/org/<organization-id>/settings, and looks likeorg_01jcq6k2x3f0vb8m8n9r3t4w5y.
When you add a GitHub organization, bifrost looks it up on GitHub and stores its immutable account id. Access is bound to that id rather than the name: renaming the GitHub organization keeps the authorization working, and if the old name is later freed and claimed by someone else, their workflows cannot obtain tokens for your bifrost organization. The name shown in the portal is the login at the time of linking.
Adding or removing a GitHub organization requires the organization edit permission and is recorded in the audit log. Removing a GitHub organization immediately stops its workflows from obtaining new access tokens.
Exchange the token in a workflow
Section titled “Exchange the token in a workflow”A workflow needs the id-token: write permission to request an OIDC token. The token is requested with your bifrost
organization id as audience and posted to the token endpoint, which returns the access token to use against the
integration API.
name: Upload SBOMon: push: branches: [main]
jobs: upload-sbom: runs-on: ubuntu-latest permissions: id-token: write # Required to request the GitHub OIDC token contents: read env: BIFROST_ORG_ID: org_01jcq6k2x3f0vb8m8n9r3t4w5y # Your bifrost organization id steps: - uses: actions/checkout@v4
# ... build your application and generate sbom.json ...
- name: Get bifrost access token run: | # Request a GitHub OIDC token with the bifrost organization id as audience GITHUB_OIDC_TOKEN=$(curl -sSf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \ "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$BIFROST_ORG_ID" | jq -r .value)
# Exchange it for a bifrost access token BIFROST_ACCESS_TOKEN=$(curl -sSf -X POST https://portal.bifrostsec.com/oauth2/token \ -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \ -d subject_token_type=urn:ietf:params:oauth:token-type:jwt \ -d subject_token="$GITHUB_OIDC_TOKEN" | jq -r .access_token)
# Mask the token in logs and pass it on to later steps echo "::add-mask::$BIFROST_ACCESS_TOKEN" echo "BIFROST_ACCESS_TOKEN=$BIFROST_ACCESS_TOKEN" >> "$GITHUB_ENV"
- name: Upload SBOM run: | curl -sSf -X POST \ "https://portal.bifrostsec.com/api/v2/service/my-service/version/sbom?version=1.2.3" \ -H "Authorization: Bearer $BIFROST_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ --data-binary @sbom.jsonThe access token is valid for 10 minutes. Request it in the step that uses it, or right before, rather than at the start of a long job.
Token endpoint reference
Section titled “Token endpoint reference”POST https://portal.bifrostsec.com/oauth2/token with a form-encoded body (application/x-www-form-urlencoded).
No client authentication is required, the OIDC token itself is the credential.
| Parameter | Value |
|---|---|
grant_type | urn:ietf:params:oauth:grant-type:token-exchange |
subject_token | The GitHub OIDC token |
subject_token_type | urn:ietf:params:oauth:token-type:jwt or urn:ietf:params:oauth:token-type:id_token |
audience | Optional. The only accepted value is integration-api, which is also the default. |
A successful exchange returns the access token in a standard OAuth 2.0 token response:
{ "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "expires_in": 600, "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"}Failed exchanges return HTTP 400 with an OAuth 2.0 error response. The error_description explains the cause:
{ "error": "invalid_grant", "error_description": "GitHub organization 'example' is not linked to organization 'My Org'"}| Error | Cause |
|---|---|
invalid_grant | The OIDC token is expired or not issued by GitHub Actions, its audience is not an existing bifrost organization id, or the repository owner’s GitHub account id is not an authorized GitHub organization of that bifrost organization. |
invalid_request | A required parameter is missing, or subject_token_type is not supported. |
invalid_target | The audience or resource parameter asks for something other than the integration API. |
unsupported_grant_type | grant_type is not the token exchange grant. |
The token endpoint is rate limited to 10 requests per minute per client address. Exchange once per job and reuse the access token across steps, as shown above.