Authentication

In order to call most of the API endpoints, one needs to obtain an access token.

Authentication is done from the perspective of a trader/end-user. Meaning that our system is expecting Log-in/Authentication credentials from a previously Signed-up user account.

This section describes how to do just that.

Example Authorization header with an access token

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

Once you have obtained your access token, you must include it in all requests that require authentication. You do so by adding a Authorization header to the request with the value Bearer <access-token> as seen in the example on the right.

Failure to include an access token when accessing protected resources will result in a 401 Unauthorized response, while a 403 Forbidden means that you don't have access to the protected resource.

All endpoints - except those described in the [authentication]() and [signup](https://coinify-trade-api.readme.io/reference/signup) sections - require you to authenticate yourself (unless explicitly specified)

Authenticate

Example success response body

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
  "token_type": "bearer",
  "expires_in": 1200, // Lifetime of access token in seconds
  "refresh_token": "wt5RoH8i6HkSQvI8kFpEBLEIB6lw8lOpYKHEz0ND9znDaAOtH1dFI32GqhvT9PGC"
}

POST https://app-api.coinify.com/auth

In order to obtain an access token, you must authenticate yourself using one of the authentication methods.

When a successful authentication has been performed, you will receive an access token and a refresh token as exemplified in the response to the right. You must use this access token to authenticate yourself to most other endpoints.

You must include a grant_type parameter (string) in the request which defines the authentication method.
The authentication endpoint currently supports the following grant_types:

password - Email/password
refresh_token - Refresh access token
offline_token - Offline token

The possible response types, regardless of the grant_type used, are listed in the following table:

HTTP Response code	JSON data
`200 OK`	Success, Response with a fresh authentication token. See example to the right.
`400 Bad request`	Error, see OAuth2 Error Response for possible error codes.

Much of the authentication interface is designed to closely match OAuth 2 (RFC 6749)

Email authentication

Example request with grant_type == "password"

{
  "grant_type": "password",
  "email": "[email protected]",
  "partnerId": "5f51bfe2-d08a-4b43-9d5c-405fd2f2ede6",
  "password": "password"
}

Use this grant_type to authenticate a user with a combination of email address and password.

Request parameter	Type	Description
`grant_type`	string	`password` - Authenticate using email and password.
`partnerId`	string	Id of the partner the user belongs to.
`email`	string	Email address of user to authenticate.
`password`	string	User's password.

Refresh access token

Example request with grant_type == "refresh_token"

{
  "grant_type": "refresh_token",
  "refresh_token": "wt5RoH8i6HkSQvI8kFpEBLEIB6lw8lOpYKHEz0ND9znDaAOtH1dFI32GqhvT9PGC"
}

The access token that you received upon authentication is only valid for 20 minutes, while the refresh token is valid for 24 hours. After the access token has expired, you can obtain a new one by either (1) re-authenticating or by (2) refreshing your token. This endpoint allows you to refresh your token without requiring the user to re-authenticate. For this reason, the Log in/Log out button is automatically removed from the trade widget menu to provide a better user experience.

Request parameter	Type	Description
`grant_type`	string	`refresh_token` - Refresh using a refresh token.
`refresh_token`	string	The refresh token obtained from the previous authentication response.

Offline token

Example request with grant_type == "offline_token"

{
    "grant_type": "offline_token",
    "offline_token": "A3873gbnvgHgniehfq8QHkSQvI8kFpEBsiudhAS83Nat2g7ASB2GqhvT9PGC"
}

Example response for authentication request

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
  "refresh_token": "wt5RoH8i6HkSQvI8kFpEBLEIB6lw8lOpYKHEz0ND9znDaAOtH1dFI32GqhvT9PGC",
  "token_type": "bearer",
  "expires_in": 1200 // Lifetime of access token in seconds
}

The offline token is used exactly as you would use a refresh token, except that it doesn't expire.

This token does not expire (it's life-long).

Request parameter	Type	Description
`grant_type`	string	`offline_token` - Authenticate using an offline token, that does not expire.
`offline_token`	string	The offline token obtained upon signup.

Sign out (Revoke refresh token)

Example request

{
  "token_type_hint": "refresh_token",
  "token": "wt5RoH8i6HkSQvI8kFpEBLEIB6lw8lOpYKHEz0ND9znDaAOtH1dFI32GqhvT9PGC"
}

POST https://app-api.coinify.com/auth/revoke

If the user wants to sign out, the client will have to revoke the refresh token and "forget" the current access token. This endpoint allows you to revoke a refresh token, so it is no longer valid.

Request parameter	Type	Description
`token_type_hint`	string	Must be `refresh_token`
`token`	string	The refresh token obtained from the authentication response

The possible response types are listed in the following table:

HTTP Response code	JSON data
`204 No Content`	Success, Empty response body
`400 Bad request`	Error, see OAuth2 Error Response for possible error codes.

See RFC 7009 for OAuth2 standard on revoking tokens.

Deactivate account

PUT https://user.coinify.com/me/deactivate

This will make your account unusable and the only way to activate it again is to contact Coinify Support.

If you wish to deactivate your account, you can make the above request. The only expected payload is the Authentication HTTP Header.

You can only deactivate your own account.

A deactivated account can not obtain an access token and thus is unable to use the parts of the API that require an access token.

Response

HTTP Response code	JSON data
`204 No Content`	Success, Empty response body
`500 Server Error`	Error, fulfilling the request.