token

Returns access token as well as refresh token.

When the access token is expired, your app can obtain a new token as described in Reissue Access Token section below.

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

# Access Token Initial Obtaining

POST /v1/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 (opens new window)
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 (opens new window). 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 Reissue 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('&')
});

# Example of Getting Token via Signer

import { Signer } from '@waves/signer';
import { ProviderWeb } from '@waves.exchange/provider-web';

async function getToken() {
    const provider = new ProviderWeb(url, true);
    const signer = new Signer({ NODE_URL: node });
    signer.setProvider(provider);

    const client_id = "waves.exchange";
    const chain_code = "W";
    const seconds = Math.round((Date.now() + 1000 * 60 * 60 * 24 * 7) / 1000);
    const message = `${chain_code}:${client_id}:${seconds}`;

    const { publicKey } = await signer.login();
    const signature = await signer.signMessage(message);
    const url = `https://api.waves.exchange/v1/oauth2/token`;
    const data = await fetch(url, {
        method: 'POST',
        headers: {
            'Content-type': 'application/x-www-form-urlencoded'
        },
        body: [
            "grant_type=password",
            "scope=general",
            `username=${encodeURIComponent(publicKey)}`,
            "password=" + encodeURIComponent(`${seconds}:${signature}`),
            `client_id=${client_id}`
        ].join('&')
    }).then(result => result.json());

   return data.access_token;
}


const token = await getToken();

# Reissue Access Token

POST /v1/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.

# 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('&')
});