Exchange Carrier OIDC Token for Hiya JWT
POST/v1/auth/token
Exchanges a carrier-issued OIDC access token for a Hiya-scoped JWT bearer token.
Overview
This endpoint implements a federated token exchange flow:
- The client obtains an OIDC access token from the carrier's identity provider
- The client presents this token to Hiya's backend
- Hiya validates the token (issuer, audience, signature, and claims)
- Upon successful validation, Hiya mints a short-lived JWT for API authorization
Token Validation
Hiya validates the following claims from the carrier OIDC token:
- iss (issuer): Must match the configured carrier identity provider
- aud (audience): Must include Hiya's registered client ID
- exp (expiration): Token must not be expired
- sub (subject): Used to identify the user account
Response
On success, returns a Hiya JWT token with:
- Short expiration time (configurable, typically 1 hour)
- Scoped claims for least-privilege API access
- Refresh token for obtaining new access tokens