Authentication Token

The /oauth/token will provide you with an authentication token to access the Bitwave API.

Overview

Bitwave’s APIs require an OAuth-style access token for every request. Tokens are obtained by sending a POST request to the /oauth/token endpoint with your client credentials. Once you have a valid token, include it in the Authorization header of subsequent API calls.

This guide walks through the token request process, explains the request and response fields, and provides example requests.

Endpoint Details

Use the following endpoint to obtain a new authentication token:

Field	Value
Method	`POST`
URL	`https://api.bitwave.io/oauth/token` — prepend your API base URL.
Content-Type	`application/x-www-form-urlencoded`, unless otherwise specified.
Request Body	Parameters depend on your grant type, such as client credentials or another OAuth flow. You must supply your API key and secret, and possibly `grant_type` and `scope`.
Returns	A JSON object containing `access_token`, `token_type`, `expires_in`, and optionally `refresh_token`.

Note: In some versions of the Bitwave API, the URL may include a version prefix, such as https://api.bitwave.io/v2/oauth/token. Confirm the exact path in the official reference. For most client-credential flows, grant_type is client_credentials and a scope may be required.

Request Steps

Follow these steps to obtain a token. Replace the field names with the exact names expected by the API once you verify them in the documentation.

Prepare your credentials.
Construct the request body.
Send a POST request.
Parse the response.
Include the token in subsequent requests.

Request Body Parameters

client_id: Your Bitwave API key.
client_secret: Your Bitwave API secret.
grant_type: The OAuth grant type. For client-credential flows, use client_credentials.
scope: Optional permission scope for your token, if required.

Request Flow

Prepare your credentials: Have your Bitwave API key and API secret, also called client ID and client secret, available. Store them securely, such as in environment variables.
Construct the request body: Create a form-encoded body, or JSON if the API allows it, containing your credentials.
Send a POST request: Submit the request to the /oauth/token endpoint. Include the Content-Type header appropriate to your request body format.
Parse the response: If successful, the API returns an object with an access_token. Extract this value for use in subsequent calls. Also note the expires_in property, which indicates how many seconds the token remains valid.
Include the token: Set the HTTP header Authorization: Bearer ACCESS_TOKEN on every API request you make. When the token expires, repeat the token request process or use a refresh token if the API supports it.

Response Fields

The token endpoint returns a JSON object. Common fields include:

Field	Description
access_token	The bearer token you must include in the `Authorization` header for subsequent requests.
token_type	Usually `bearer`, indicating that the token is used in a Bearer authorization header.
expires_in	Number of seconds until the token expires. Request a new token after this time.
refresh_token	Optional long-lived token that can be exchanged for a new access token without resupplying client credentials.

Example Requests

Use the following examples to request an access token.

Example: cURL

curl -X POST https://api.bitwave.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_API_KEY&client_secret=YOUR_API_SECRET&grant_type=client_credentials"

Replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials. If scopes are required, append a scope parameter to the request body.

Example: Node.js

The following Node.js example defines a small OAuth client to fetch a token and an Auth wrapper for convenience:

import axios from 'axios';

interface OauthResponse {
  access_token: string;
  token_type: 'Bearer';
  expires_in: number;
}

class Oauth {
  route = '/oauth';
  clientId: string;
  clientSecret: string;
  baseUrl: string;

  constructor(baseUrl: string, clientId: string, clientSecret: string) {
    this.baseUrl = baseUrl;
    this.clientId = clientId;
    this.clientSecret = clientSecret;
  }

  public async getToken(): Promise<OauthResponse> {
    const url = `${this.baseUrl}${this.route}/token`;
    const data = {
      grant_type: 'client_credentials',
      client_id: this.clientId,
      client_secret: this.clientSecret,
    };

    const resp = await axios.post<OauthResponse>(url, data);
    return resp.data;
  }
}

class Auth {
  static async getToken(
    baseUrl: string,
    clientId: string,
    clientSecret: string
  ): Promise<OauthResponse> {
    const oauth = new Oauth(baseUrl, clientId, clientSecret);
    return await oauth.getToken();
  }
}

async function main() {
  const apiKey = process.env.BITWAVE_API_KEY!;
  const apiSecret = process.env.BITWAVE_API_SECRET!;
  const authResp = await Auth.getToken('https://api.bitwave.io', apiKey, apiSecret);

  console.log('Access token:', authResp.access_token);
}

main().catch((err) => console.error(err));

After retrieving the token, include it in the Authorization header as Bearer ACCESS_TOKEN when calling Bitwave APIs. If you want to see how this token is used to create transactions, refer to the GitLab sample’s Import class for an example of passing the token to a TransactionServiceGatewayImpl.

Error Handling

When a request fails, the API returns a non-200 status code with an error object. Common failure scenarios include:

400 Bad Request: Missing or invalid parameters, such as an incorrect grant_type or a missing required field.
401 Unauthorized: Invalid client credentials or an expired token. Double-check your API key and secret, then request a new token.
403 Forbidden: Insufficient scopes or permissions for the requested action. Ensure you are requesting the correct scope.
5XX Server Errors: Issues on Bitwave’s side. Retry after a delay or contact Bitwave support.

If the response includes an error field, inspect the error and error_description strings for more details.

Best Practices

Secure your secrets: Never hard-code your client credentials. Use environment variables or a secrets manager.
Handle expiration: Check the expires_in value and refresh the token before it expires. If a refresh_token is provided, use it to obtain a new access_token without re-sending your client secret.
Scope usage: Request only the scopes your application needs. This limits exposure if the token is leaked.
Error logging: Log error responses for debugging and to help identify misconfigurations or network issues.
Rate limits: Be aware of any rate limits or throttling on the token endpoint to avoid being blocked.

Next Steps

With a valid access token, you can authenticate calls to other Bitwave APIs, such as retrieving transactions or importing data. See the respective endpoint guides for details on constructing those requests.

Overview

Bitwave’s APIs require an OAuth-style access token for every request. Tokens are obtained by sending a POST request to the /oauth/token endpoint with your client credentials. Once you have a valid token, include it in the Authorization header of subsequent API calls.

This guide walks through the token request process, explains the request and response fields, and provides example requests.

Endpoint Details

Use the following endpoint to obtain a new authentication token:

Field	Value
Method	`POST`
URL	`https://api.bitwave.io/oauth/token` — prepend your API base URL.
Content-Type	`application/x-www-form-urlencoded`, unless otherwise specified.
Request Body	Parameters depend on your grant type, such as client credentials or another OAuth flow. You must supply your API key and secret, and possibly `grant_type` and `scope`.
Returns	A JSON object containing `access_token`, `token_type`, `expires_in`, and optionally `refresh_token`.

Note: In some versions of the Bitwave API, the URL may include a version prefix, such as https://api.bitwave.io/v2/oauth/token. Confirm the exact path in the official reference. For most client-credential flows, grant_type is client_credentials and a scope may be required.

Request Steps

Follow these steps to obtain a token. Replace the field names with the exact names expected by the API once you verify them in the documentation.

Prepare your credentials.
Construct the request body.
Send a POST request.
Parse the response.
Include the token in subsequent requests.

Request Body Parameters

client_id: Your Bitwave API key.
client_secret: Your Bitwave API secret.
grant_type: The OAuth grant type. For client-credential flows, use client_credentials.
scope: Optional permission scope for your token, if required.

Request Flow

Prepare your credentials: Have your Bitwave API key and API secret, also called client ID and client secret, available. Store them securely, such as in environment variables.
Construct the request body: Create a form-encoded body, or JSON if the API allows it, containing your credentials.
Send a POST request: Submit the request to the /oauth/token endpoint. Include the Content-Type header appropriate to your request body format.
Parse the response: If successful, the API returns an object with an access_token. Extract this value for use in subsequent calls. Also note the expires_in property, which indicates how many seconds the token remains valid.
Include the token: Set the HTTP header Authorization: Bearer ACCESS_TOKEN on every API request you make. When the token expires, repeat the token request process or use a refresh token if the API supports it.

Response Fields

The token endpoint returns a JSON object. Common fields include:

Field	Description
access_token	The bearer token you must include in the `Authorization` header for subsequent requests.
token_type	Usually `bearer`, indicating that the token is used in a Bearer authorization header.
expires_in	Number of seconds until the token expires. Request a new token after this time.
refresh_token	Optional long-lived token that can be exchanged for a new access token without resupplying client credentials.

Example Requests

Use the following examples to request an access token.

Example: cURL

curl -X POST https://api.bitwave.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_API_KEY&client_secret=YOUR_API_SECRET&grant_type=client_credentials"

Replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials. If scopes are required, append a scope parameter to the request body.

Example: Node.js

The following Node.js example defines a small OAuth client to fetch a token and an Auth wrapper for convenience:

import axios from 'axios';

interface OauthResponse {
  access_token: string;
  token_type: 'Bearer';
  expires_in: number;
}

class Oauth {
  route = '/oauth';
  clientId: string;
  clientSecret: string;
  baseUrl: string;

  constructor(baseUrl: string, clientId: string, clientSecret: string) {
    this.baseUrl = baseUrl;
    this.clientId = clientId;
    this.clientSecret = clientSecret;
  }

  public async getToken(): Promise<OauthResponse> {
    const url = `${this.baseUrl}${this.route}/token`;
    const data = {
      grant_type: 'client_credentials',
      client_id: this.clientId,
      client_secret: this.clientSecret,
    };

    const resp = await axios.post<OauthResponse>(url, data);
    return resp.data;
  }
}

class Auth {
  static async getToken(
    baseUrl: string,
    clientId: string,
    clientSecret: string
  ): Promise<OauthResponse> {
    const oauth = new Oauth(baseUrl, clientId, clientSecret);
    return await oauth.getToken();
  }
}

async function main() {
  const apiKey = process.env.BITWAVE_API_KEY!;
  const apiSecret = process.env.BITWAVE_API_SECRET!;
  const authResp = await Auth.getToken('https://api.bitwave.io', apiKey, apiSecret);

  console.log('Access token:', authResp.access_token);
}

main().catch((err) => console.error(err));

After retrieving the token, include it in the Authorization header as Bearer ACCESS_TOKEN when calling Bitwave APIs. If you want to see how this token is used to create transactions, refer to the GitLab sample’s Import class for an example of passing the token to a TransactionServiceGatewayImpl.

Error Handling

When a request fails, the API returns a non-200 status code with an error object. Common failure scenarios include:

400 Bad Request: Missing or invalid parameters, such as an incorrect grant_type or a missing required field.
401 Unauthorized: Invalid client credentials or an expired token. Double-check your API key and secret, then request a new token.
403 Forbidden: Insufficient scopes or permissions for the requested action. Ensure you are requesting the correct scope.
5XX Server Errors: Issues on Bitwave’s side. Retry after a delay or contact Bitwave support.

If the response includes an error field, inspect the error and error_description strings for more details.

Best Practices

Secure your secrets: Never hard-code your client credentials. Use environment variables or a secrets manager.
Handle expiration: Check the expires_in value and refresh the token before it expires. If a refresh_token is provided, use it to obtain a new access_token without re-sending your client secret.
Scope usage: Request only the scopes your application needs. This limits exposure if the token is leaked.
Error logging: Log error responses for debugging and to help identify misconfigurations or network issues.
Rate limits: Be aware of any rate limits or throttling on the token endpoint to avoid being blocked.

Next Steps

With a valid access token, you can authenticate calls to other Bitwave APIs, such as retrieving transactions or importing data. See the respective endpoint guides for details on constructing those requests.

Overview

Bitwave’s APIs require an OAuth-style access token for every request. Tokens are obtained by sending a POST request to the /oauth/token endpoint with your client credentials. Once you have a valid token, include it in the Authorization header of subsequent API calls.

This guide walks through the token request process, explains the request and response fields, and provides example requests.

Endpoint Details

Use the following endpoint to obtain a new authentication token:

Field	Value
Method	`POST`
URL	`https://api.bitwave.io/oauth/token` — prepend your API base URL.
Content-Type	`application/x-www-form-urlencoded`, unless otherwise specified.
Request Body	Parameters depend on your grant type, such as client credentials or another OAuth flow. You must supply your API key and secret, and possibly `grant_type` and `scope`.
Returns	A JSON object containing `access_token`, `token_type`, `expires_in`, and optionally `refresh_token`.

Note: In some versions of the Bitwave API, the URL may include a version prefix, such as https://api.bitwave.io/v2/oauth/token. Confirm the exact path in the official reference. For most client-credential flows, grant_type is client_credentials and a scope may be required.

Request Steps

Follow these steps to obtain a token. Replace the field names with the exact names expected by the API once you verify them in the documentation.

Prepare your credentials.
Construct the request body.
Send a POST request.
Parse the response.
Include the token in subsequent requests.

Request Body Parameters

client_id: Your Bitwave API key.
client_secret: Your Bitwave API secret.
grant_type: The OAuth grant type. For client-credential flows, use client_credentials.
scope: Optional permission scope for your token, if required.

Request Flow

Prepare your credentials: Have your Bitwave API key and API secret, also called client ID and client secret, available. Store them securely, such as in environment variables.
Construct the request body: Create a form-encoded body, or JSON if the API allows it, containing your credentials.
Send a POST request: Submit the request to the /oauth/token endpoint. Include the Content-Type header appropriate to your request body format.
Parse the response: If successful, the API returns an object with an access_token. Extract this value for use in subsequent calls. Also note the expires_in property, which indicates how many seconds the token remains valid.
Include the token: Set the HTTP header Authorization: Bearer ACCESS_TOKEN on every API request you make. When the token expires, repeat the token request process or use a refresh token if the API supports it.

Response Fields

The token endpoint returns a JSON object. Common fields include:

Field	Description
access_token	The bearer token you must include in the `Authorization` header for subsequent requests.
token_type	Usually `bearer`, indicating that the token is used in a Bearer authorization header.
expires_in	Number of seconds until the token expires. Request a new token after this time.
refresh_token	Optional long-lived token that can be exchanged for a new access token without resupplying client credentials.

Example Requests

Use the following examples to request an access token.

Example: cURL

curl -X POST https://api.bitwave.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_API_KEY&client_secret=YOUR_API_SECRET&grant_type=client_credentials"

Replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials. If scopes are required, append a scope parameter to the request body.

Example: Node.js

The following Node.js example defines a small OAuth client to fetch a token and an Auth wrapper for convenience:

import axios from 'axios';

interface OauthResponse {
  access_token: string;
  token_type: 'Bearer';
  expires_in: number;
}

class Oauth {
  route = '/oauth';
  clientId: string;
  clientSecret: string;
  baseUrl: string;

  constructor(baseUrl: string, clientId: string, clientSecret: string) {
    this.baseUrl = baseUrl;
    this.clientId = clientId;
    this.clientSecret = clientSecret;
  }

  public async getToken(): Promise<OauthResponse> {
    const url = `${this.baseUrl}${this.route}/token`;
    const data = {
      grant_type: 'client_credentials',
      client_id: this.clientId,
      client_secret: this.clientSecret,
    };

    const resp = await axios.post<OauthResponse>(url, data);
    return resp.data;
  }
}

class Auth {
  static async getToken(
    baseUrl: string,
    clientId: string,
    clientSecret: string
  ): Promise<OauthResponse> {
    const oauth = new Oauth(baseUrl, clientId, clientSecret);
    return await oauth.getToken();
  }
}

async function main() {
  const apiKey = process.env.BITWAVE_API_KEY!;
  const apiSecret = process.env.BITWAVE_API_SECRET!;
  const authResp = await Auth.getToken('https://api.bitwave.io', apiKey, apiSecret);

  console.log('Access token:', authResp.access_token);
}

main().catch((err) => console.error(err));

After retrieving the token, include it in the Authorization header as Bearer ACCESS_TOKEN when calling Bitwave APIs. If you want to see how this token is used to create transactions, refer to the GitLab sample’s Import class for an example of passing the token to a TransactionServiceGatewayImpl.

Error Handling

When a request fails, the API returns a non-200 status code with an error object. Common failure scenarios include:

400 Bad Request: Missing or invalid parameters, such as an incorrect grant_type or a missing required field.
401 Unauthorized: Invalid client credentials or an expired token. Double-check your API key and secret, then request a new token.
403 Forbidden: Insufficient scopes or permissions for the requested action. Ensure you are requesting the correct scope.
5XX Server Errors: Issues on Bitwave’s side. Retry after a delay or contact Bitwave support.

If the response includes an error field, inspect the error and error_description strings for more details.

Best Practices

Secure your secrets: Never hard-code your client credentials. Use environment variables or a secrets manager.
Handle expiration: Check the expires_in value and refresh the token before it expires. If a refresh_token is provided, use it to obtain a new access_token without re-sending your client secret.
Scope usage: Request only the scopes your application needs. This limits exposure if the token is leaked.
Error logging: Log error responses for debugging and to help identify misconfigurations or network issues.
Rate limits: Be aware of any rate limits or throttling on the token endpoint to avoid being blocked.

Next Steps

With a valid access token, you can authenticate calls to other Bitwave APIs, such as retrieving transactions or importing data. See the respective endpoint guides for details on constructing those requests.

200Ok