---
updatedAt: 2025-09-22T17:22:19.000Z
agentTools:
projectIndex: https://developer.bitpay.com/llms.txt
---
# Request an API Token
Facades: `public`, `merchant`
> 📘 Note
>
> For e-commerce implementation, we advise merchants to generate a standard pos facade token directly from the [BitPay dashboard ](https://bitpay.com/dashboard/merchant/api-tokens)(make sure "Require Authentication" is disabled) and use the "Tokens" API endpoint only to request higher privilege tokens (typically merchant facade). Merchants only need to use this endpoint once, depending on the number of facades they want to have access to.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "test",
"version": "1.0"
},
"servers": [
{
"url": "https://test.bitpay.com"
}
],
"security": [
{}
],
"paths": {
"/tokens": {
"post": {
"summary": "Request an API Token",
"description": "Facades: `public`, `merchant`",
"operationId": "get-token",
"parameters": [
{
"name": "Content-Type",
"in": "header",
"description": "Must be set to `application/json` for requests to the BitPay API",
"required": true,
"schema": {
"type": "string",
"default": "application/json"
}
},
{
"name": "X-Accept-Version",
"in": "header",
"description": "Must be set to `2.0.0` for requests to the BitPay API",
"required": true,
"schema": {
"type": "string",
"default": "2.0.0"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Client identity based on BitAuth identity protocol, also known as SIN (System Identification Number)"
},
"facade": {
"type": "string",
"description": "Can be `merchant`, `pos`, or `payout`. If passed in the body of the request together with the id parameter, leave the pairingCode parameter out.",
"default": "pos"
},
"label": {
"type": "string",
"description": "Optional. Token label, may include spaces, underscores, and dashes. BitPay invites the merchants to pass their Business Name or website in this field."
},
"pairingCode": {
"type": "string",
"description": "Optional.
- Client Initiated Pairing: If you do not pass a pairing code in the body of the request, you need to send the `id` and `facade` parameters. This will allow you to request API tokens with higher privileges (`merchant`, or `payout` facades)
- Server Initiated Pairing: If you pass a pairing code in the body of the request, leave the
facade parameter out. The pairing code which can be generated from the BitPay dashboard (with `\"Require Authentication\"` enabled) only allows you to request a `pos` facade token with authentication, meaning it will be necessary to cryptographically sign every request using this token, just like the other facades with higher privileges.
"
}
}
}
}
}
},
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"data\": [\n {\n \"policies\": [\n {\n \"policy\": \"id\",\n \"method\": \"inactive\",\n \"params\": [\n \"Tf2yXsY49iFyDfxt3b2kf9VPRMwPxxAyCRW\"\n ]\n }\n ],\n \"token\": \"G7XM9fcM1gtCN7DUr8ZWtPGVFLTKiYWanHR4kvqsnjP3\",\n \"facade\": \"merchant\",\n \"label\": \"merchantwebsite.com\",\n \"dateCreated\": 1621340364865,\n \"pairingExpiration\": 1621426764865,\n \"pairingCode\": \"C4Lg7oW\"\n }\n ]\n}"
}
},
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"policies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"policy": {
"type": "string",
"example": "id"
},
"method": {
"type": "string",
"example": "inactive"
},
"params": {
"type": "array",
"items": {
"type": "string",
"example": "Tf2yXsY49iFyDfxt3b2kf9VPRMwPxxAyCRW"
}
}
}
}
},
"token": {
"type": "string",
"example": "G7XM9fcM1gtCN7DUr8ZWtPGVFLTKiYWanHR4kvqsnjP3"
},
"facade": {
"type": "string",
"example": "merchant"
},
"label": {
"type": "string",
"example": "merchantwebsite.com"
},
"dateCreated": {
"type": "integer",
"example": 1621340364865,
"default": 0
},
"pairingExpiration": {
"type": "integer",
"example": 1621426764865,
"default": 0
},
"pairingCode": {
"type": "string",
"example": "C4Lg7oW"
}
}
}
}
}
}
}
}
}
},
"deprecated": false,
"security": []
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": false,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```