coss.comdocs

Exchange an OIDC token

POST
/v1/oidc/token

Exchanges an OIDC ID token from a CI or hosting provider (GitHub Actions, Vercel, GitLab, CircleCI or any issuer an environment trusts) for a short-lived access token, so no API key has to be stored there. The token must come from the credential's issuer, be issued for its audience and meet every condition on its claims. Needs no API key. Every refusal is the same invalid_oidc_token; the reason is in the environment's logs. DELETE /v1/api_key with the access token revokes just that token.

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Request Body

application/json
  1. body
credential_id*string

The OIDC credential to exchange through (oidc_…, shown on the environment's API keys page). Not a secret: it can live in a workflow file.

Length1 <= length <= 64
token*string

The OIDC ID token your CI or hosting provider issued to this job or function (a JWT).

Length1 <= length <= 16384

Response Body

The access token.

application/json
  1. response

A short-lived access token exchanged for an OIDC ID token.

object*"oidc_access_token"
Value in"oidc_access_token"
access_token*string

Use it as an API key (Authorization: Bearer …) until it expires. It can do what the credential allows, in the credential's environment.

token_type*"Bearer"
Value in"Bearer"
expires_in*integer

Seconds until it expires.

expires_at*string

When it expires (ISO 8601).

environment_id*string

The environment it works in.

import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.oidc.exchangeToken({  credential_id: "oidc_01k7c8m4q2f3e9v6t5r1n0p8yz",  token: "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9.eyJpc3MiOiIuLi4ifQ.c2lnbmF0dXJl",});
{  "object": "oidc_access_token",  "access_token": "coss_live_oidc_3q2-7wEVR6aZ1xYb0pN4kL8sT5uC9dF2gH6jM1nP0rQ",  "token_type": "Bearer",  "expires_in": 3600,  "expires_at": "2026-11-13T13:00:00.000Z",  "environment_id": "env_01k7c8m4q2f3e9v6t5r1n0p8yz"}