| Description |
Depending on the parameters used for the call, this endpoint can serve one of two purposes:
1) It allows you to retrieve a new refresh_token following initial "code" flow authorization.
2) It may be used to generate a valid access_token anytime, using an existing and valid refresh_token.Notice: This endpoint can't be used by apps that do not possess a client_secret! |
| URL |
https://my.hidrive.com/oauth2/token |
| Parameters |
client_id (required)
|
| This is the app-specific client_id you received after your app registration. |
client_secret (required)
|
| This is the app-specific client_secret you received after your app registration (unless you registered an app of type "browser"). |
grant_type (required)
|
| The value of this parameter determines which of the following parameters will be required for a successful request.
grant_type=authorization_code is usually called only once, after the /client/authorize callback, which provided a code. Thus, making the equally named parameter code required.
grant_type=refresh_token requires you to send a refresh token as value of the parameter refresh_token. This is the main use of this endpoint and allows for automated retrieval of access_token without the need for additional approval within the validity of the given refresh_token. |
code (optional)
|
| This parameter is mutually exclusive with parameter refresh_token depending on parameter grant_type.
Use the code you received from the /client/authorize callback.
Note: an authorization code is short-lived (five minutes) and therefore needs to be used quickly after obtaining it. |
refresh_token (optional)
|
| This parameter is mutually exclusive with parameter code depending on parameter grant_type.
Use the refresh_token you received from the initial call to this endpoint using grant_type=authorization_code |
|
| Example Usage |
cURL
|
With grant_type=authorization_code
curl -X POST \
--data "client_id=<client_id> \
&client_secret=<client_secret> \
&grant_type=authorization_code \
&code=<...>" \
https://my.hidrive.com/oauth2/token
With grant_type=refresh_token
curl -X POST \
--data "client_id=<client_id> \
&client_secret=<client_secret> \
&grant_type=refresh_token \
&refresh_token=<...>" \
https://my.hidrive.com/oauth2/token
|
|
| Response |
In both cases you'll get a valid access_token. Whereas grant_type=authorization_code creates it, either case returns the valid refresh_token.
It is strongly suggested to store this refresh_token in a secure and persistent way for future use.Example result:
{
"refresh_token":"...",
"expires_in":3600,
"userid":"...",
"access_token":"...",
"alias":"...",
"token_type":"Bearer",
"scope":"ro,user"
}
|
| Errors |
401 Unauthorized
|
HiDrive refresh tokens have a default validity of 3 months.
Calling this endpoint with grant_type=refresh_token and an expired (but known) refresh_token value will result in an error 401 with the following return value:
{
"error_description":"refresh token is no longer valid",
"error":"error"
}
An application must always be prepared to react to this error, preferably by redirecting the user back to /client/authorize, to be able to get a new refresh token. |
400 Bad Request
|
Usually "Bad Request" errors return JSON with the following structure:
{
"error_description":"...",
"error":"invalid_request"
}
The error_description string describes the details of what went wrong and is mostly self-explanatory.
Possible values are:
"missing client_id"
"missing client_secret"
"missing grant_type"
"missing refresh_token"
"missing code"
"empty client_id"
"empty client_secret"
"empty grant_type"
"empty refresh_token"
"empty code"
"invalid client_id (param auth)"
"invalid client_secret (param auth)"
"invalid refresh_token (format)"
"invalid code (format)"
The following JSON is returned in case of a mismatching, unrecognized or locked pair of client_id and client_secret.
{
"error_description":"unknown client_id or wrong client_secret",
"error":"invalid_client"
}
If you use the grant_type=authorization_code flow and your code is either invalid or expired (after 600s), you'll see:
{
"error_description":"unknown code",
"error":"invalid_grant"
}
If you use the grant_type=refresh_token flow and your refresh_token value is not a known refresh token of your client, you'll see:
{
"error_description":"unknown refresh token",
"error":"invalid_grant"
}
|
|
