HiDrive Developer » 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

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

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

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>

<redirect_uri>?code=<authorization_code>

maximum

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

<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

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

<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

<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

<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)

<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

curl -X POST \ --data "client_id=<client_id> \ &client_secret=<client_secret> \ &grant_type=authorization_code \ &code=<...>" \ https://my.hidrive.com/oauth2/token

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

curl -X POST \ --data "client_id=<client_id> \ &client_secret=<client_secret> \ &grant_type=refresh_token \ &refresh_token=<...>" \ https://my.hidrive.com/oauth2/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"

}

{ "refresh_token":"...", "expires_in":3600, "userid":"...", "access_token":"...", "alias":"...", "token_type":"Bearer", "scope":"ro,user" }

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

}

{ "error_description":"refresh token is no longer valid", "error":"error" }

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

}

{ "error_description":"...", "error":"invalid_request" }

{
     "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)"

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

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

}

{ "error_description":"unknown client_id or wrong client_secret", "error":"invalid_client" }

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

}

{ "error_description":"unknown code", "error":"invalid_grant" }

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

}

{ "error_description":"unknown refresh token", "error":"invalid_grant" }

{
     "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 curl -X POST --data "access_token=<...>" https://my.hidrive.com/oauth2/tokeninfo 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"

}

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

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

}

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

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

Parameter format error

{

"error_description": "invalid access_token (format)",

"error": "invalid_request"

}

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

{
     "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 curl -X POST \ --data "token=<...> \ &client_id=<client_id> \ &client_secret=<client_secret>" \ https://my.hidrive.com/oauth2/revoke 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"

}

{ "error_description":"...", "error":"invalid_request" }

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

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

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

OAuth2 Endpoints

GET /client/authorize

client_id (required)

response_type (required)

scope (optional)

lang (optional)

state (optional)

redirect_uri (optional)

javascript

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

“token flow” (app type “browser”)

Redirected parameter errors

POST /oauth2/token

client_id (required)

client_secret (required)

grant_type (required)

code (optional)

refresh_token (optional)

cURL

401 Unauthorized

400 Bad Request

POST /oauth2/tokeninfo

access_token (required)

cURL

400 Bad Request

POST /oauth2/revoke

client_id (required)

client_secret (required)

token (required)

cURL

400 Bad Request