Signup

Currently, only trader signup is supported.

The signup endpoints reside under https://app-api.coinify.com/signup.

Trader signup

Minimal example request for POST /signup/trader

{
  "partnerId": "5f51bfe2-d08a-4b43-9d5c-405fd2f2ede6",
  "email": "[email protected]",
  "profile": {
    "address": {
      "country": "DK"
    }
  }
}

Maximal example request for POST /signup/trader

{
  "partnerId": "5f51bfe2-d08a-4b43-9d5c-405fd2f2ede6",
  "email": "[email protected]",
  "password": "mypassword",
  "accountType": "individual",
  "profile": {
    "address": {
      "state": "CA",
      "country": "US"
    }
  },
  "generateOfflineToken": true,
  "consentAdditionalMails": true
}

Example response for POST /signup/trader

{
  "trader": {
    "id": 754035
  },
  // Offline token, only included if requested explicitly, and only in the signup response.
  "offlineToken": "aGFja2VydHlwZXIuY29tIGlzIG15IElERQ=="
}

POST https://app-api.coinify.com/signup/trader

This endpoint allows you to sign up a new trader

The email address of the new trader must be verified before creating a trade. See Email validation for more information.

Request object

The parameters in the request object are as follows:

Parameter	Type	Default	Description
`email`	String	Required	Email address of the new trader (and user)
`password`	String	`null`	The password of the user used in combination with the email address to sign in. If omitted or `null`, user cannot sign in until they manually reset their password.
`partnerId`	UUID	Required	Provide a Coinify partner ID to associate this trader with a specific Coinify partner.
`accountType`	String	`individual`	Set account type if signing up as a business, can be `corporate` (will default to `individual`)
`profile`	Object	`null`	Object with additional information about the trader.
→`address`	Object	`null`	Object with information about the trader's physical address.
→`state`	String	`null`	ISO 3166-2 state/province. Required if `country` is 'US'
→`country`	String	Required	ISO 3166-1 alpha-2 country code.
`trustedEmailValidationToken`	String	`null`	(Only for trusted Coinify partners, `partnerId` must be provided) Signed message from partner for automatic validation of `email`. See Trusted email validation.
`generateOfflineToken`	Boolean	`false`	Also generate and return an offline token for the new trader. If set to `true`, an offline token is created for the new trader and returned in the response with the key `offlineToken`.
`consentAdditionalMails`	Boolean	Required	Determines whether the user consents to receive additional email from Coinify.

Response object

The success response object contains the following fields:

Key	Type	Description
`trader`	Object	See example
`offlineToken`	String	(Optional) An offline token for the new trader. Only created and returned if the `generateOfflineToken` request parameter is explicitly set to `true`

Error object

If the signup request fails for some reason, the response contains the first error encountered during the signup process:

HTTP status code	Error code	Description
201	`N/A`	Sign up successful
400	`invalid_request`	There was something wrong with the signup request. See the `error_description` argument for a specific, human-readable error message.
400	`email_address_and_partner_id_in_use`	The provided email address is already associated with an existing trader that belongs to the specified partner.
400	`invalid_trusted_email_validation_token`	The supplied `trustedEmailValidationToken` was invalid.
500	`internal_error`	An internal error happened during signup. Please try again later.

Email validation

When signing up a trader with Coinify, we have to ensure that the email address provided is valid and that the new trader can receive emails sent to that address. This can happen in one of two ways:

Manual validation: An email is sent to the specified address containing a 6-digit verification code that the user must provide in order to validate their email address.
Trusted validation (Only for Coinify partners): The partner cryptographically signs a message stating that the partner has validated the email address previously. This signed message must be provided in the signup request. The email address is then immediately trusted as valid by proxy.

Only trusted Coinify partners can use trusted validation. If you are not a trusted Coinify partner, you must use manual validation. As a trusted Coinify partner, you must collect the country of residence from your end-users input and forward this data in the country parameter upon trader signup.

Trusted validation

While the manual validation described previously is easier to implement, it sometimes doesn't make sense to perform an additional email validation from a user experience perspective - if the user is signing up for Coinify through a partner, the partner will most likely already have validated the user's email address. In this case, the partner can issue a signed message to Coinify stating that the user's email address has already been validated by the partner.

Coinify then trusts the partner to have validated the email address themselves, and the email address is immediately marked as validated, and the user won't have to perform any manual action to validate the email address to Coinify.

Example of 2048-bit RSA public key in PEM format.

Coinify must have the partner's public key (RSA/EC) in advance for trusted validation to work

In essence, for trusted validation to work, the partner must have generated a cryptographic key pair and sent the public key to Coinify. Before the signup, the partner then signs a message containing the same email address as the email parameter in the signup. If the email address of the signed message equals that of the signup request and the signature of the message is valid using the public key, Coinify considers the email address as valid. If the email addresses differ or the signature is invalid, the signup request will fail with a invalid_trusted_email_validation_token error code.

Signed message details

The signed message containing the email address must be a JSON Web Token (JWT) and passed in the signup request as the trustedEmailValidationToken parameter.

The message must be signed using one of the following algorithms:

JWT `alg` name	Algorithm
`RS256`	RSASSA using SHA-256 hash algorithm
`RS384`	RSASSA using SHA-384 hash algorithm
`RS512`	RSASSA using SHA-512 hash algorithm
`ES256`	ECDSA using P-256 curve and SHA-256 hash algorithm
`ES384`	ECDSA using P-384 curve and SHA-384 hash algorithm
`ES512`	ECDSA using P-521 curve and SHA-512 hash algorithm

JWT Header

Example JWT header using RS256 algorithm

{
  "alg": "RS256",
  "typ": "JWT"
}

The header must contain exactly two values (see example to the right):

Key	Type	Description
`typ`	String	JWT identifier. Must contain the string `"JWT"`.
`alg`	String	Signature algorithm. Must be one of the allowed signature algorithms listed above.

JWT payload

Example JWT payload for email address [email protected]

{
  "email": "[email protected]",
  "exp": 1467331200  // Expires at 2016-07-01 00:00:00 UTC
}

The payload of the JWT can contain the following values (see example to the right):

Key	Type	Default value	Description
`email`	String	Required	Email address. The valid email address.
`exp`	Integer	Never expire	Expiration time. Unix timestamp for when this JWT will no longer be valid. If given, the message will only be valid for validating the email address up until the given time. If not given, the message will always be valid.

If the payload contains other values than the ones specified in the table above, it is considered invalid.

JWT example

Example JWT token (with added line break)

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
eyJlbWFpbCI6ImpvaG5kb2VAZXhhbXBsZS5jb20iLCJleHAiOjE0NjczMzEyMDB9.
qpn5iey9H86OwxsH8npw_IkmRIE3nxJKgl3FqRP0lSjc5XCA71XcMppwU2WqELgu
Cl7arKSmiHdp9GTu_sfXTk1bSiZMYfpfO810y02l_IrSh4YcZeYko3wW2QpVfgZF
lqwoNQcBM878mveUAmRKfhtQjohHcjLb5YDS2uVf2AFvXFUS443HL25_DC1IuUzr
YCv9pMBI4YHVxWIPU25EERMA03pa0O1XoF9LJR4uTBmKcQTC94IDbbf5GKz29Htk
kEvmx9z5cl0TZGxsRSwzsF0xI6v1taGzKo0NCn8AXpXkjiuffHm_Ml_v5L-bHGhZ
EYs25682iuS6K9Nl1FAggw

The above JWT contains the following header and payload. The token is signed with the private key matching the public key example shown previously.

// Header
{
  "alg": "RS256",
  "typ": "JWT"
}

// Payload
{
  "email": "[email protected]",
  "exp": 1467331200  // Expires at 2016-07-01 00:00:00 UTC
}