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

In other words, a signed request identifies an application’s identity in addition to the identity accompanying granted permissions of the end-user the application is making API calls on behalf of, represented by the user’s access token.

User authentication requires the app key and secret from your Cryptohopper app and the access token and access secret from the user you are trying to act on the behalf of. More info about the Oauth methods underneath:

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. (optional).
  • 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.