Partner registration

Partner registration is a one-time manual handshake. Coordinate it with your CI HUB contact.

Inputs to CI HUB

Item	Format	Notes
Issuer URL	absolute URL string	Goes into the `iss` claim of every JWT minted by the partner. Identifies the partner platform.
JWKS URL	absolute URL string	Endpoint CI HUB fetches to retrieve public keys. Reachable from CI HUB infrastructure; HTTPS in production.
Audience	absolute URL string	Expected `aud` claim. Defaults to `https://api.ci-hub.com`.
Maximum token age	seconds	Upper bound on `(exp - iat)` for partner JWTs. Default 3600.
Operational contact	email and name	On-call recipient for production incidents involving the integration.

Outputs from CI HUB

Item	Purpose
Registered issuer (confirmed)	Sanity check against the value used in JWT signing. Must match exactly, including trailing slash.
Audience (confirmed)	Goes into the `aud` claim.
`maxTokenAge` (confirmed)	Upper bound enforced by the exchange.
Stage environment access	Base URL and account configuration for development.
Production handoff date	Production is enabled after stage verification.

No client secret or partner ID is returned. The pairing of iss and the partner's JWKS is the credential.

JWKS contract

CI HUB fetches the partner JWKS and caches the response for 10 minutes. Every partner JWT must reference a kid present in the JWKS at exchange time.

Minimal JWKS response:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "your-kid",
      "use": "sig",
      "alg": "RS256",
      "n": "<modulus, base64url>",
      "e": "AQAB"
    }
  ]
}

Field	Required	Notes
`kty`	yes	`RSA`. EC keys are not supported.
`kid`	yes	Stable identifier. The `kid` in the JWT header must equal one of these.
`use`	recommended	`sig` for signing keys.
`alg`	recommended	`RS256`. If absent, RS256 is assumed.
`n`, `e`	yes	RSA public key. RSA-2048 recommended.

Key rotation

Publish the new key alongside the old key in the JWKS. Wait at least 10 minutes (the cache window) before signing with the new kid. Remove the old key at the next rotation.

Signing the partner JWT

Any RS256-capable JWT library works. The contract is the JWT itself, not the language. The example below uses Node's jsonwebtoken.

import fs from 'node:fs'
import jwt from 'jsonwebtoken'

const privateKey = fs.readFileSync('./private.pem')
const now = Math.floor(Date.now() / 1000)

const partnerJwt = jwt.sign(
  {
    iss: 'https://auth.your-platform.example.com',
    aud: 'https://api.ci-hub.com',
    sub: 'user-12345',
    email: 'jane@customer.example.com',
    iat: now,
    exp: now + 3600,
  },
  privateKey,
  {
    algorithm: 'RS256',
    keyid: 'your-kid',
  }
)

Mint a fresh JWT per token exchange. Do not cache the partner JWT; cache the CI HUB tokens it returns.

The full claim specification is on the exchange token endpoint page.

Integrations are built against stage at https://stage.ci-hub.com/api/v1. Verification requires a successful token exchange, a DAM login round-trip, and at least one content call against stage. CI HUB replicates the configuration to production at https://live.ci-hub.com/api/v1 after verification.

Onboarding checklist

Partner side:

Generate an RSA-2048 keypair. Store the private key in the partner's secret store. Expose the public key via the JWKS endpoint.
Send issuer URL, JWKS URL, requested audience, maximum token age, and operational contact to CI HUB.
Sign a test JWT and call POST /auth/exchangeToken against stage. Verify a CI HUB access token is returned.
Call GET /auth/checkToken with the access token in the Authorization: Bearer header. Verify the response status is 200.
After CI HUB promotes the configuration to production, switch the base URL to the live host and repeat steps 3 and 4.

Step 4 confirms the CI HUB token is valid, the user is associated with the partner company, and the SDK subscription is active. A full DAM login round-trip and content call become possible once the DAM Auth references are in place.

CI HUB side (operational; happens after step 2 above):

Register the partner in sdk.partners configuration.
Provision the partner company and SDK subscription.
Notify the partner that stage is ready.

Exchange token endpoint →

Request, response, and error contract