---
updatedAt: 2026-05-21T16:39:58.000Z
---
# Exchange a valid bearer token for an authenticated browser session
This endpoint takes an authentication bearer token in the header, or as the query parameter “access_token”. However, for security purposes, it is recommended that the token is passed in by using the POST API call.
It uses “scoped=true” as a query parameter optionally. When “scoped=true” is given, the cookie created is be used to login to app scoped application. If “scoped=true” is not given, the cookie created is used to login to non-app scoped application.
It uses “redirect_url” as a query parameter as optionally. When “redirect_url” is given, the call will redirect to the redirect URL with the authenticated session.
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"version": "1.0.0",
"description": "Authentication",
"title": "Authentication"
},
"servers": [
{
"url": "https://{tenanturl}",
"variables": {
"tenanturl": {
"default": "{tenant_url}",
"description": "URL of your IBM Security Verify tenant"
}
}
}
],
"tags": [
{
"name": "Authentication Token Exchange"
}
],
"paths": {
"/v1.0/auth/session": {
"get": {
"tags": [
"Authentication Token Exchange"
],
"summary": "Exchange a valid bearer token for an authenticated browser session",
"description": "This endpoint takes an authentication bearer token in the header, or as the query parameter “access_token”. However, for security purposes, it is recommended that the token is passed in by using the POST API call.\n
It uses “scoped=true” as a query parameter optionally. When “scoped=true” is given, the cookie created is be used to login to app scoped application. If “scoped=true” is not given, the cookie created is used to login to non-app scoped application.\n
It uses “redirect_url” as a query parameter as optionally. When “redirect_url” is given, the call will redirect to the redirect URL with the authenticated session.\n",
"operationId": "exchangeToken1",
"parameters": [
{
"name": "scoped",
"in": "query",
"description": "If true, it creates a session for app scoped application login. If false, it creates a session for non app scoped application login",
"schema": {
"type": "boolean"
}
},
{
"name": "access_token",
"in": "query",
"description": "The access token used to create the authenticated browser session. Useful for testing, but it is recommended that the token be passed in the Authorization header, as URL parameters can be intercepted.",
"schema": {
"type": "string"
}
},
{
"name": "redirect_url",
"in": "query",
"description": "The URL where the request will be redirected after the session is created. The URL should be URL encoded or the authenticated redirect may fail. An error is returned if the URL is not allowed.
A valid URL must match one of these conditions:
- Starts with the tenant name, \"https://tenantname.com\"
- Is a relative path, it starts with \"/\"
- It matches one of the URLs in the list of allowed URL in the Session Exchange management API",
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"description": "An access token was successfully exchanged for an IBM Security Verify session credential.",
"content": {}
},
"302": {
"description": "Returned when the \"redirect_url\" parameter is passed in. After a successful token exchange the browser will be redirected to the redirect_url",
"content": {}
},
"400": {
"description": "The system cannot process the request because no access token was found in the request. An access token must be present in either the 'Authorization' HTTP header or in the query parameter 'access_token'.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/BadRequest_1"
}
}
}
},
"401": {
"description": "The request either provided no authentication or the authentication was unsuccessful.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Unauthorized_0"
}
}
}
},
"403": {
"description": "The access token used does not allow access to the requested resource.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Forbidden_1"
}
}
}
},
"500": {
"description": "An unexpected error occurred while trying to acquire necessary user data.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/ServerError"
}
}
}
}
},
"x-category": "Authentication",
"x-publicAPI": "true"
}
}
},
"components": {
"schemas": {
"ServerError": {
"required": [
"messageDescription",
"messageId"
],
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "The message key identifier",
"example": "CSIAH0601E"
},
"messageDescription": {
"type": "string",
"description": "A requester locale-specific descriptive message",
"example": "An internal error occurred in the Authentication Service"
}
}
},
"BadRequest_1": {
"required": [
"messageDescription",
"messageId"
],
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "The message key identifier",
"example": "CSIAH0643E"
},
"messageDescription": {
"type": "string",
"description": "A requester locale-specific descriptive message",
"example": "The system cannot process the request because no access token was found in the request. An access token must be present in either the 'Authorization' HTTP header or in the query parameter 'access_token'."
}
}
},
"Unauthorized_0": {
"required": [
"messageDescription",
"messageId"
],
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "The message key identifier",
"example": "CSIAH0611E"
},
"messageDescription": {
"type": "string",
"description": "A requester locale-specific descriptive message",
"example": "The access token included in the request is not valid."
}
}
},
"Forbidden_1": {
"required": [
"messageDescription",
"messageId"
],
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "The message key identifier",
"example": "CSIAK4300E"
},
"messageDescription": {
"type": "string",
"description": "A requester locale-specific descriptive message",
"example": "The authenticated user is not permitted to perform the requested operation."
}
}
}
}
},
"x-original-swagger-version": "2.0",
"x-explorer-enabled": false
}
```