Exchange Code for Tokens

Server-to-server call. Exchange the authorization code (with your PKCE code_verifier) for an access token and a refresh token, or use grant_type refresh_token to get a new access token. Access tokens last 1 hour and refresh tokens 30 days; every refresh rotates the refresh token. Send the access token as a Bearer token to the Panda IDX MCP servers.

POST/api/oauth/token

Authentication

Noneno credentials

Public clients send client_id and code_verifier only. Confidential clients (token_endpoint_auth_method client_secret_post) also send client_secret in the body or as HTTP Basic credentials. The body can be JSON or application/x-www-form-urlencoded.

Query Parameters

grant_typestring

required

authorization_code or refresh_token.

Default:authorization_code

authorization_coderefresh_token

client_idstring

required

The client_id from POST /register or your Client ID Metadata Document URL.

codestring

optional

The authorization code from the callback. Required for grant_type authorization_code.

redirect_uristring

optional

The same redirect_uri used in the authorize step.

code_verifierstring

optional

The PKCE verifier whose SHA-256 you sent as code_challenge. Required for public clients.

refresh_tokenstring

optional

Required for grant_type refresh_token.

resourcestring

required

Must be the Panda IDX MCP server.

Default:https://api.pandaidx.com/mcp

client_secretstring

optional

Only for confidential clients registered with client_secret_post.

Responses

200Success

application/json

access_tokenstring

Bearer token for the MCP servers. Valid for expires_in seconds.

refresh_tokenstring

Use it with grant_type refresh_token. Valid for 30 days and rotated on every use.

token_typestring

Always Bearer.

expires_innumber

Access token lifetime in seconds (3600).

scopestring

The granted scopes, space separated.

Errors

400invalid_request, invalid_grant (expired, reused or mismatched code, failed PKCE), invalid_target (resource is not the MCP server)

401invalid_client: client authentication failed

Complete the authorization flow

Use this endpoint after the user returns to your redirect_uri with an authorization code. Send the exchange from your backend or your local connector, never from a public web page. The body carries the code, the PKCE code_verifier you generated before the authorize step, your client_id and the MCP resource. Use the same redirect_uri as in the authorization step.

Store and refresh tokens safely

Access tokens last one hour and refresh tokens 30 days. Every refresh returns a new refresh token and invalidates the old one, so save the new value each time. Keep tokens and any client_secret out of public repositories, analytics events and browser URLs. If the user disconnects the connector in Dashboard → Apps, or you call the revoke endpoint, the tokens stop working immediately.

Where tokens work

Panda IDX OAuth tokens are accepted by the MCP servers at https://api.pandaidx.com/mcp and https://api.pandaidx.com/mcp/builder. The REST endpoints of the Site API do not use OAuth: they take the site's public key in the key query parameter.

OAuth authorization · MCP server · API setup guide

Request

curl --request POST \
  --url "https://app.pandaidx.com/api/oauth/token" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "grant_type": "authorization_code",
    "code": "{{auth_code}}",
    "client_id": "{{client_id}}",
    "redirect_uri": "{{redirect_uri}}",
    "code_verifier": "{{code_verifier}}",
    "resource": "https://api.pandaidx.com/mcp"
  }'

Response200 OK

{
  "access_token": "pnd_example_access_token",
  "refresh_token": "pnd_example_refresh_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile listings contacts"
}