Skip to content

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 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.

Terminal window
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 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.
  1. Open your organization in the bifrost portal and go to the GitHub card under Settings.
  2. Click Add GitHub Organization and enter the GitHub organization (or user) name that owns your repositories, for example bifrostsec.
  3. 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 like org_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.

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 SBOM
on:
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.json

The 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.

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.

ParameterValue
grant_typeurn:ietf:params:oauth:grant-type:token-exchange
subject_tokenThe GitHub OIDC token
subject_token_typeurn:ietf:params:oauth:token-type:jwt or urn:ietf:params:oauth:token-type:id_token
audienceOptional. 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'"
}
ErrorCause
invalid_grantThe 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_requestA required parameter is missing, or subject_token_type is not supported.
invalid_targetThe audience or resource parameter asks for something other than the integration API.
unsupported_grant_typegrant_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.