Authentication

Oauth2 Authentication

Cryptohopper uses Oauth2 to provide authorized access to its API.

Using Oauth2

Understanding the way OAuth2 works can help create and debug applications which use Cryptohoppers’s API. To use OAuth, an application must

Obtain grant tokens to act on behalf of a user account.
Switch grant tokens for access tokens.
Authorize all HTTP requests it sends to Cryptohopper’s APIs.

The user authentication method of authentication allows an app to act on behalf of the user, as the user.

Example: if a developer wanted to build a feature that would allow a trading bot to buy a certain currency through their platform using the buy endpoint, the developer would have to use user authentication to get permission from the user to trade on their behalf.

Every API request your app makes on behalf of a user carries that user's access token. The token tells Cryptohopper which app is calling and which permissions the user granted it.

To get an access token your app needs its app key (client_id) and app secret (client_secret). Send the access token in the access-token header of every API request; an Authorization: Bearer header is not accepted. More about the OAuth methods below:

Oauth2 methods

authorize

With the authorize endpoint users can sign in to Cryptohopper and grant access to the application. After successfull granting access or after any errors, the user will be redirected to the redirect URL. If the redirect URL is not specified in the request, the redirect URL of the application configuration is used. In the GET parameters on the redirect URL you will receive the grant token which can be exchanged for an access_token.

Endpoint: https://www.cryptohopper.com/oauth2/authorize

Accepts: GET

Returns: code, state in GET on the redirect url

Parameters:

client_id: The app key of your application.
response_type: The response type should contain the text: code.
redirect_uri: The redirect URL where users will be redirected to after the Oauth process.
state: Extra parameter to recognise requests on the application side. Will be returned to the redirect URL.
scope: A comma separated list of scopes, for example: read,notifications,manage,trade.

token

The token endpoint is used to change a grant token/code for a valid access_token.

Endpoint: https://www.cryptohopper.com/oauth2/token

Accepts: POST in application/json

Returns: access_token and refresh_token in application/json

Parameters:

client_id: The app key of your application.
client_secret: The app secret of your application.
grant_type: The grant type should contain the text: authorization_code.
redirect_uri: The redirect URL of your application.
code: The grant token/code.

Succesfull response codes

When a request to the access_token endpoint is succesfull, the user will be redirected to the redirect URL with an grant token passed as GET parameters.

A succesfull request to the token endpoint will have a 200 response code and will include an access_token in the body which can be used to authenticate API calls with.

Error response codes

Errors returned to the redirect URL are recognizable by the returned GET parameter: error=1. Underneath you will find possible error messages:

App key is invalid.
The signature is invalid.
App key cannot be empty.
User did not give permission to the app.

Scopes

Your app asks for scopes in the scope parameter of the authorize request, and the user sees them before granting access. Ask only for what your app needs. The API reference lists the scopes of every endpoint.

`read`	Read hoppers, positions, orders, trades, configs and marketplace data. Nearly every endpoint needs it.
`manage`	Create, change and delete hoppers, configs, templates and strategies, and cancel or remove orders.
`trade`	Place orders, sell, short or DCA positions, and use the panic button.
`notifications`	Receive webhook notifications about the user's hoppers.
`user`	Read and change the user's profile, credits, purchases and account settings.
`email`	Read the user's email address.