All API requests on behalf of a user must be authenticated by an OAuth2 access token which is obtained via a standard OAuth2 (two-legged) Resource Owner Password Credentials flow as specified in the OAuth 2.0 Resource Owner Password Credentials Grant.

If you are familiar with the Resource Owner Password Credentials flow or are using an OAuth2 client library, you can skip the following explanation.

Resource Owner Password Credentials Flow

The Resource Owner Password Credentials flow allows exchanging the username and password of a user for an access token and, optionally, a refresh token. This flow has significantly different security properties than other OAuth flows. The primary difference is that the user's password is accessible to the application. This requires strong trust of the application by the user.

Steps to Obtain and Use the OAuth2 Access Token

Step 1: Ask the User for Their Credentials

The first step is asking the user to provide their credentials to the application, i.e., username and password. An application would typically display this as fields for user input.

Step 2: Exchange the Credentials for an Access Token

We need to make an HTTP POST request to the authorization server, providing the credentials and client information. You can find the authorization server URL in the Upvest Clientele API reference. The Content-Type message header field must be set to application/x-www-form-urlencoded.

Encode the HTTP message body in the application/x-www-form-urlencoded format with the following fields:

grant_type
Specified as "password" for this flow.

scope
The data your application is requesting access to. The optional values that the Upvest Blockchain API accepts are read, write, echo, wallet, and transaction, concatenated as a space-separated string.

client_id
The value provided to you when you registered your application. Achieve registration through the Account Management app.

client_secret
The value provided to you when you registered your application.

username
The username provided by the resource owner encoded as UTF-8.

password
The password provided by the resource owner encoded as UTF-8.

Here's an example via the curl command-line HTTP client:

curl -d "grant_type=password" \
-d "client_id=b11sz5z2RfQi2AYJ6wSDE" \
-d "client_secret=29046103482436420" \
-d "scope=read write echo wallet transaction" \
-d "username=frikkice" \
-d "password=secret" \
https://api-playground.eu.upvest.co/1.0/clientele/oauth2/token

If the user-provided credentials are successfully authenticated, the Upvest authorization server returns an application/json response containing an access_token:

{
    "access_token": "zSMWkPGyMatY8oYVsFEv1Pr9sjMS3Q",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "read write echo wallet transaction",
    "refresh_token": "iYmTFUisTiNSwdwFaNQ63U1a6bOBNs"
}

What does each of these response parameters mean?

access_token
The access token used to access the API on behalf of the user who provided their credentials. This is the only required item in the response.

expires_in
The time in seconds that the access token is valid for since its issuing.

token_type
The type of access token. Use this to specify the type of access token in the HTTP Authorization header.

scope
The scope that the access token is valid for.

refresh_token
A special kind of token that can be used to obtain a renewed access token.

Step 3: Call the API

You merely need to provide the access token via an HTTP Authorization header.

Here's an example curl request:

curl -H 'Authorization: Bearer wdNAngDP64kDkYF4DI1ZhQny2Ck6Ej' \
https://api-playground.eu.upvest.co/1.0/kms/wallets/