OAuth2 Endpoints

GET /client/authorize

Description Each authentication flow initially starts at this endpoint.
An app must forward the user or open a new browser to this location with the correct parameters.
URL https://my.hidrive.com/client/authorize
Parameters

client_id (required)
This is the app-specific client_id you received after your app registration.

response_type (required)
Use response_type=token if you registered a browser app. This will result in you getting an access_token returned upon approval.

Use response_type=code for server- and native apps, to receive an authorization_code upon approval.

scope (optional)
This parameter represents the comma separated list of privileges to be requested from the user.
Starting with a role, which can be one of (user, admin, owner); Followed by an indicator for read-only or read-write access to the user data, (ro, rw)For example, request administrative privileges and read-write access:

scope=admin,rw

Notice, that the user is free to chose a scope with permissions differing from those requested. In this case, the authorized scope information will be added to the redirect_uri call.

Default: user,ro

lang  (optional)
You may change the language in which the authorization page is shown to the user by providing a valid value for lang. Languages are represented by ISO_639-1 codes.

The currently supported languages are:

  • de
  • en (default)
  • es
  • fr
  • nl
  • sv

state (optional)
This string value is used for maintaining a client-side state. The provided value will be returned via the redirect_uri as a parameter.

redirect_uri (optional)
The value must resemble one of the redirect_uris set up for your app.
However, currently you can only register a default uri.
Example Usage

javascript

 
window.location.href = "https://my.hidrive.com/client/authorize" 
   + "?client_id=<client_id>&response_type=code&scope=admin,rw";

 
Response Note: an authorization code is short-lived and needs to be used within five minutes at the /oauth2/token endpoint.

In case of “oob”, the user will be provided with a short code, to enter into your app. Otherwise, the response will be a redirect back to your redirect_uri providing information as follows:

“code flow” (app type “server”, “native”)
minimal

<redirect_uri>?code=<authorization_code>

maximum

<redirect_uri>?code=<authorization_code>&scope=<approved_scope>&state=<given_state>

“token flow” (app type “browser”)
minimal

<redirect_uri>?access_token=<access_token>&expires_in=3600&token_type=Bearer

maximum

<redirect_uri>?access_token=<access_token>&expires_in=3600&token_type=Bearer&scope=<approved_scope>&state=<given_state>

 
Errors This endpoint handles errors in two different ways.
If client_id verification failed or you provided an invalid value for lang or redirect_uri, errors will be displayed to the user on the authorization page.If you provided a valid client_id, the following errors will be redirected back to your registered redirect_uri:

Redirected parameter errors
You provided a valid client_id but no response_type at all.

<redirect_uri>?error=unsupported_response_type&error_description=missing+response_type

You provided a valid client_id and an unsuitable response_type. (e.g. token for a server-type app)

<redirect_uri>?error=unauthorized_client&error_description=unsuitable+authorization-flow:+token

You provided a valid client_id and response_type but an invalid value for scope (e.g. “foo”)

<redirect_uri>?error=invalid_request&error_description=invalid+scope+(%27foo%27)

POST /oauth2/token

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" 
}

POST /oauth2/tokeninfo

Description An endpoint you may use to get information about your current access_token. The response will include the granted scope, expiry time, user alias and your client_id.
URL https://my.hidrive.com/oauth2/tokeninfo
Parameters

access_token (required)
A valid HiDrive access_token (not base64 encoded).
Invalid or expired token will result in a 400 Bad Request error.
Example Usage

cURL

 
curl -X POST --data "access_token=<...>" https://my.hidrive.com/oauth2/tokeninfo
Response For a valid access_token the response consists of current information about the expiry, scope, client_id and HiDrive user alias.

{
     "expires_in": 3202, 
     "client_id": "<client_id>", 
     "alias": "foobar", 
     "scope": "rw,owner"
}
Errors

400 Bad Request
Invalid or expired access_token

{
     "error_description": "unknown access token", 
     "error": "invalid_token"
}

Parameter format error

{
     "error_description": "invalid access_token (format)", 
     "error": "invalid_request" 
}

POST /oauth2/revoke

Description Revoke an active access_token or refresh_token.

Revoking a refresh_token will also invalidate all related access_token. Revoking the refresh_token is the easiest way to accomplish a logout mechanism for your app. This is a functionality we explicitly encourage you to implement.

Note: use a content-type of application/x-www-form-urlencoded.
URL https://my.hidrive.com/oauth2/revoke
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”)

token (required)
The access_token or refresh_token you wish to revoke with the call.
Example Usage

cURL

 
curl -X POST \
--data "token=<...> \ 
&client_id=<client_id> \ 
&client_secret=<client_secret>" \ 
https://my.hidrive.com/oauth2/revoke
Response In case of success this endpoint returns a simple 200 response without content.
Errors

400 Bad Request
Bad Request errors return a JSON hash 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 token"
"empty client_id"
"empty client_secret"
"empty token"
"invalid client_id (param auth)"
"invalid client_secret (param auth)"
"invalid token (format)"
"invalid_token"