How to Authenticate Requests

Step 1: Obtain an API Key

1. In the ConductorOne app, navigate to the User’s API Settings page by clicking your username at the bottom of the screen and selecting API Keys.
2. Click Create credential.
3. Enter a descriptive name for your API key.
4. Your new key is created, and its Client ID and Client Secret are generated and displayed.

⚠️ Note: The Client Secret is shown only once — make sure to securely store this information.

Details about the Client ID and Client Secret

• Client ID
  A stable format that includes a random ID, the base hostname, and the use-case.
  Format: <random-id>@<hostname>/<use-case>
  Example:

  [email protected]/pcc

• Client Secret
  Format:

  secret-token:conductorone.com:${base64url encoded JWK}

  This contains an ed25519 private key. Example:

  secret-token:conductorone.com:v1:eyJrdHkiOiJPS1AiLCJjcnYiOiJFZDI1NTE5IiwieCI6IkMySEx5Y0d6eUhfZDQwcjJvejZoNkpqdndvRVFBZ0FTRVc2eDB6emh6Y2MiLCJkIjoiLTgzVkxXUVUtZVhQY0ZCWVhDb2NpU29XVmhrYnRXUm9zdkZUZ3JqcXNVbyJ9

🔐 Keep your Client ID and Client Secret secure. They play a critical role in the integrity of your API access.

---

Step 2: Determine Your API Root and Token Endpoint

Extracting the Hostname from the Client ID

Your Client ID is in the format <random-id>@<hostname>/<use-case>. The hostname is the part after @ and before /.

Example:

Client ID: [email protected]/pcc
Hostname: acme.conductor.one

Identifying the Token Endpoint

With the hostname:

Token endpoint = https://<hostname>/auth/v1/token

Example:

https://acme.conductor.one/auth/v1/token

Identifying the API Root

API root = https://<hostname>/api/v1

Example:

https://acme.conductor.one/api/v1

---

Step 3: Get an Access Token

You can obtain an access token via one of two methods:

Option 1: Basic Access Token

1. Make a POST request to the token endpoint with content type application/x-www-form-urlencoded.
2. Include the following data:

grant_type=client_credentials
client_id=${CLIENT_ID}
client_secret=${CLIENT_SECRET}

Example JSON Response:

{
  "access_token": "secret_access_token_value",
  "token_type": "Bearer",
  "expires_in": 600
}

---

Option 2: Access Token via Signed Client Assertion

A more secure approach using JWTs signed with the private key from your Client Secret.

JWT Claims Required:

• iss: ${CLIENT_ID}
• sub: ${CLIENT_ID}
• aud: Tenant’s Domain
• exp: Expiration time within 5 minutes of now

Request Data:

grant_type=client_credentials
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_id=${CLIENT_ID}
client_assertion=${CLIENT_ASSERTION}

Example JSON Response:

{
  "access_token": "secret_access_token_value",
  "token_type": "Bearer",
  "expires_in": 600
}

👉 Cone OAuth Token Source Example (GitHub)

---

Making Requests to the API Using an Access Token

Once you have the token, include it in your requests using the Authorization header.

Example:

GET /api/v1/endpoint HTTP/1.1
Host: acme.conductor.one
Authorization: Bearer ${ACCESS_TOKEN}

Replace ${ACCESS_TOKEN} with your actual token.

Token Expiration

• Tokens expire after expires_in seconds.
• Track expiration and refresh your token before it expires to avoid disruption.

---