Skip to main content
Bitwage supports two authentication methods. Choose the one that fits your integration:
MethodBest forHeader format
API KeyServer-to-server integrationsAuthorization: Basic <ACCESS_TOKEN>
OAuth 2.0User-authorized accessAuthorization: Bearer <ACCESS_TOKEN>

​
API Key authentication

API key authentication is the simplest way to get started. It is ideal for server-side integrations where your application acts on behalf of a single business account.

​
Get your API key

  1. Go to Settings > API in your Bitwage Business Account.
  2. Register a new Authentication App (if you haven’t already).
  3. Click Self Auth beside the “Authorized Authentication Apps” header.
  4. Click on your app — your API key is the Access Token field.

​
Use your API key

Include the API key in the Authorization header: 
curl -X GET "https://api.sandbox.bitwage.com/api/company" \
  -H "Authorization: Basic YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company_id": "YOUR_COMPANY_ID"}'
For write operations (POST, PATCH, DELETE) with API key auth, include an Idempotency-Key header to prevent duplicate processing. See the Idempotency guide for details.

​
OAuth 2.0 authentication

OAuth 2.0 uses the Authorization Code flow. This lets your application act on behalf of a Bitwage user after they grant permission.

​
Step 1: Configure your application

After creating your Authentication App, note your Client ID and Client Secret from the app widget under “My Authentication Apps”. Keep your Client Secret secure.

​
Step 2: Request an authorization code

Redirect the user to the Bitwage authorization endpoint: 
https://app.bitwage.com/authorize?client_id=YOUR_CLIENT_ID&state=YOUR_CSRF_TOKEN
After the user authorizes your app, they are redirected to: 
{redirect_uri}?code={authorization_code}&state={your_csrf_token}

​
Step 3: Exchange the code for an access token

Exchange the authorization code for an access token: 
curl -X POST "https://api.sandbox.bitwage.com/oauth2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTHORIZATION_CODE",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "authorization_code"
  }'
The response includes your access token along with the user and company IDs: 
{
  "access_token": "abc123...",
  "user_id": "1234567890",
  "company_id": "9876543210"
}

​
Step 4: Use the access token

Include the access token in subsequent requests: 
curl -X GET "https://api.sandbox.bitwage.com/api/company" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company_id": "YOUR_COMPANY_ID"}'

​
OAuth scopes

When registering your app, select the scopes your integration needs:
ScopeDescription
c_company_detailRead company details
c_company_worker_listList company workers
c_company_worker_invitations_listList worker invitations
c_company_workers_inviteInvite workers
c_company_workers_payCreate payroll
u_user_createCreate users
u_user_updateUpdate users
u_user_update_docUpload user documents
u_user_detailRead user details
u_user_document_listList user documents
u_user_payer_createCreate payers
u_user_payer_updateUpdate payers
u_user_payer_detailRead payer details
u_user_payer_listList payers
u_user_bank_detailsRead bank details
u_user_distribution_createCreate distributions
u_user_distribution_updateUpdate distributions
u_user_distribution_detailRead distribution details
u_user_distribution_listList distributions
u_user_kyc_initiateInitiate KYC verification