---
title: "Exchange an OIDC id_token for a dotAuth session-ref"
method: POST
path: "/api/v1/dotauth/oauth/exchange"
tags: ["dotAuth"]
---

# Exchange an OIDC id_token for a dotAuth session-ref

`POST /api/v1/dotauth/oauth/exchange`

## Request

- Base URL: `https://docs.anzworldline-solutions.com.au`
- URL: `https://docs.anzworldline-solutions.com.au/api/v1/dotauth/oauth/exchange`
- Auth: none declared
- TypeScript: <https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/docs/api/v1/dotauth/oauth/exchange/post.ts> (a function with typed inputs; its response is checked against the schema)

Validates the caller-supplied id_token against the configured OIDC provider's JWKS (signature, iss, aud == our client_id, exp, nonce), resolves or JIT-provisions the matching dotCMS user, and returns an opaque session-ref bound to that user.

## Request body

- OAuthExchangeForm
  - `idToken` string, required
  - `nonce` string, required
  - `expirationDays` integer

## Response `200`

Token exchange succeeded

- ResponseEntityOAuthExchangeView
  - `errors` ErrorEntity[]
    - `errorCode` string
    - `message` string
    - `fieldName` string
  - `entity` OAuthExchangeView
    - `sessionRef` string
    - `expiresAt` string
    - `expirationDays` integer
    - `user` UserSummary
      - `userId` string
      - `email` string
      - `firstName` string
      - `lastName` string
      - `fullName` string
      - `roles` string[]
  - `messages` MessageEntity[]
    - `message` string
  - `i18nMessagesMap` object
  - `permissions` string[]
  - `pagination` Pagination
    - `currentPage` integer
    - `perPage` integer
    - `totalEntries` integer

## Other responses

- `400`: Malformed payload or non-OIDC provider configured
- `401`: id_token failed validation (signature, iss, aud, exp, or nonce)
- `403`: Resolved dotCMS user exists but is not active
- `404`: Exchange endpoint not found
- `503`: OAuth is not configured for this site

## Changes

- **2026-10-30** `4fd8e917d458`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/changes/api/v1/dotauth/oauth/exchange/post.md)

---

[API](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api.md) - [All operations](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/revisions/4fd8e917d458?raw)