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 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.sandbox.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.sandbox.upvest.co/1.0/kms/wallets/
Updated about a month ago