POST /oauth2/token

Returns access token as well as refresh token.

When the access token is expired, your app can obtain a new token as descriped in Exchanging Refresh Token for New Access Token section below.

This method requires HTTP header Content-type: application/x-www-form-urlencoded.

Access Token Initial Obtaining

POST /oauth2/token
Content-type: application/x-www-form-urlencoded

{
  "grant_type": "password",
  "scope": "general",
  "username": "(string)",
  "password" "(string)",
  "client_id": "waves.exchange"
}

Request parameters

Field name	Description
grant_type	To initially obtain an access token specify password
scope	Specify general
username	User's public key
password	Generate password as follows: 1. Join chain ID (opens new window) character with client_id string and with token expiration Unix timestamp in seconds, using ':' separator. For example, W:waves.exchange:1584651600. 2. Convert this string to bytes. 3. Add [255, 255, 255, 1] prefix. 4. Generate Curve25519 (opens new window) signature of bytes using user's private key. 5. Join token expiration Unix timestamp in seconds with base58 encoded signature, using ':' separator. For example, 1584651600:3BU36da1h6Bzhs4tKcfkCsXWi4vEgP8eQD7rkGWJdxbRfNpky6p3p7mUJWEL9ejDsasS8nWu1g6tZpsX4. ⚠️Token expiration timestamp must be no more than a week from the current time. See also the JavaScript Example section below.
client_id	For Gateway API specify waves.exchange

Response JSON Example

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWduYXR1cmUiOiI2MUppRFBQWUZya2pw...",
  "token_type": "bearer",
  "expires_in": 1584651600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWduYXR1cmUiOiI2MUppRFBQWUZya2pw..."
}

Response Parameters

Field name	Description
access_token	Access token to use in API requests
token_type	Type of token issued. Always takes the value bearer
expires_in	Access token expiration timestamp: Unix time in seconds
refresh_token	Refresh token. After access token expiration you can exchange refresh token for a new access token, see the Exchanging Refresh Token for New Access Token section below

JavaScript Example

The example uses waves-transactions library, see documentation (opens new window) on Github.

import { libs } from "@waves/waves-transactions";

const seed = "insert your seed here";
const chain_code = "W"; // "T" for Testnet
const client_id = "waves.exchange";
const seconds = Math.round((Date.now() + 1000 * 60 * 60 * 24 * 7) / 1000); // Token for a week

const bytes = [255, 255, 255, 1, ...libs.crypto.stringToBytes(`${chain_code}:${client_id}:${seconds}`)];
const signature = libs.crypto.signBytes(seed, bytes);            

fetch('https://api.waves.exchange/v1/oauth2/token', {
    method: 'POST',
    headers: {
        'Content-type': 'application/x-www-form-urlencoded'
    },
    body: [
        "grant_type=password",
        "scope=general",
        `username=${encodeURIComponent(libs.crypto.publicKey(seed))}`,
        "password=" + encodeURIComponent(`${seconds}:${signature}`),
        `client_id=${client_id}`
    ].join('&')
});

Exchanging Refresh Token for New Access Token

POST /oauth2/token
Content-type: application/x-www-form-urlencoded

{
  "grant_type": "refresh_token",
  "scope": "general",
  "client_id": "waves.exchange",
  "refresh_token": "(string)"
}

Request parameters

Field name	Description
grant_type	To exchange a refresh token for a new access token specify refresh_token
scope	Specify general
client_id	For Gateway API specify waves.exchange
refresh_token	Refresh token. After access token expiration you can exchange refresh token for a new access token

Response JSON Example

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWduYXR1cmUiOiI2MUppRFBQWUZya2pw...",
  "token_type": "bearer",
  "expires_in": 1584109637,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWduYXR1cmUiOiI2MUppRFBQWUZya2pw..."
}

Response parameters are the same as described in the Access Token Initial Obtaining section above.

JavaScript Example

const refresh_token = "insert your refresh token here";
const client_id = "waves.exchange";

fetch('https://api.waves.exchange/v1/oauth2/token', {
    method: 'POST',
    headers: {
        'Content-type': 'application/x-www-form-urlencoded'
    },
    body: [
        "grant_type=refresh_token",
        "scope=general",
        `refresh_token=${refresh_token}`,
        `client_id=${client_id}`
    ].join('&')
});