In this section, you will find comprehensive information about the process of coinapi authentication. It covers the fundamental aspects and procedures involved in obtaining authentication for coinapi usage. Whether you are new to coinapi or seeking to enhance your understanding of the authentication process, this section will provide you with a valuable overview of the topic.

There are different types of authentication methods available to secure and control access to its services.

  • API Key - fundamental method of authentication that involves the usage of an API key for authentication and access control.

  • API Key + JWT token - extended authentication method that combines the use of an API key along with a JWT token for enhanced security and authentication. Useful when you need to share the API Key publicly, for example when accessing the CoinAPI endpoints from the frontend JavaScript code exposed to the end-users. JWT token will be required along the API Key from the CoinAPI side to perform successful authentication, and the JWT tokens can be only generated from your side as you know the secret (private key or secret) based on which JWT token with the specified expiration time are issued.

Authentication methods supported by the API

Here's an overview of the various products offered by coinapi and the supported authentication methods for each product. To use resources that require authorized access, you will need to use one of the many authenitcation methods described below.

Product nameAPIX-CoinAPI-Key headerQuery paramURL pathAuthorization headerBasic authJWTTLS Client CertSenderCompIDAWS Signature Version 4
Market DataREST
Market DataWS
Market DataFIX
Market DataS3
EMSManaged Cloud REST

X-CoinAPI-Key header

You can authorize by providing additional custom header named X-CoinAPI-Key and API key as its value.

Assuming that your API key is 73034021-THIS-IS-SAMPLE-KEY, then the authentication header you should send to us will look like:

X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY

Query string parameter (apikey)

You can authorize by providing an additional parameter named apikey with a value equal to your API key in the query string of your HTTP request.

Assuming that your API key is 73034021-THIS-IS-SAMPLE-KEY and that you want to request all exchange rates from BTC asset, then your query string should look like this: GET /v1/exchangerate/BTC?apikey=73034021-THIS-IS-SAMPLE-KEY

URL path

To ensure proper authentication when passing the API key in the URL, it is important to format it correctly. The real API key should always be preceded by the APIKEY- prefix, followed by the actual API key. For example, if your API key is 73034021-THIS-IS-SAMPLE-KEY, the URL should be structured as /APIKEY-73034021-THIS-IS-SAMPLE-KEY.

The API key can be placed at the beginning, middle, or end of the URL path. Note that the key is completely ignored when determining the path of the requested resource. Here are examples of the different placements:

  • At the beginning of the URL:
    • /APIKEY-73034021-THIS-IS-SAMPLE-KEY/v1/exchanges
  • In the middle of the URL:
    • /v1/APIKEY-73034021-THIS-IS-SAMPLE-KEY/exchanges
  • At the end of the URL:
    • /v1/exchanges/APIKEY-73034021-THIS-IS-SAMPLE-KEY

Please make sure to replace 73034021-THIS-IS-SAMPLE-KEY with your actual API key for authentication and access to the requested resources and remember to include the APIKEY- prefix before your real API key.

Authorization header

This method involves including the API key directly in the Authorization header of the API request.

Authorization: 73034021-THIS-IS-SAMPLE-KEY

Basic auth

Use Basic Authentication by setting the Authorization header with a base64 encoded string that combines your API key with a username (coinapi):

Authorization: Basic Y29pbmFwaTo3MzAzNDAyMS1USElTLUlTLVNBTVBMRS1LRVk=

In this example, Y29pbmFwaTo3MzAzNDAyMS1USElTLUlTLVNBTVBMRS1LRVk is a base64 encoded string of the username and API key (coinapi:73034021-THIS-IS-SAMPLE-KEY).

JWT token

The JWT authentication method provides a secure and efficient way to authorize requests using JSON Web Tokens (JWT). With this method, JWTs can be passed via the Authorization header in the Bearer JWT_TOKEN format.

Supported JWT Algorithms

JWT authentication method supports the following algorithms for JWT token verification with various key sizes:

  • RSASSA-PSS (e.g. PS256)
  • RSASSA-PKCS1-v1_5 (e.g. RS256)
  • ECDSA (e.g. ES256)
  • HMAC (e.g. HS256)

Enabling JWT authentication

To enable JWT authentication for your API key:

  1. Access the customer portal and import public JWT key (RSA or ECDSA) for API key.
  2. Generate JWT token using your private key (it ensures authenticity and integrity of the token)
  3. Include the generated JWT token in Authorization header of your api requests using Bearer JWT_TOKEN format.
  4. Let CoinAPI server verify the token's authenticity using the corresponding public key you've imported in step 1 during API request.

Example request with JWT authentication

To include a JWT in an API request, add the token to the Authorization header using the Bearer scheme. The format of the header is as follows:

Authorization: Bearer JWT_TOKEN

Example request header with JWT token generated using RS256 algorithm:

Authorization: Bearer eyJraWQiOiI5ODViMmQ0ZC1kMjE1LTQwN2MtODcxNi01NTIzNjA0YmM0ZTIiLCJhbGciOiJSUzI1NiJ9.ew0KICAic3ViIjogIjEyMzQ1Njc4OTAiLA0KICAibmFtZSI6ICJFWEFNUExFIFRPS0VOIiwNCiAgImlhdCI6IDE1MTYyMzkwMjIsDQogICJuYmYiOiAxNjg2MTM3MDI0LA0KICAiZXhwIjogMTcxNzY3MzAyNA0KfQ.CX6MWRSXQPKuQ_jrFCME91IwZhK8lq_2XrbDOyZ4-tPo0Ro52HA289sIfLo2LNafWQlq2lClfCN55TxyfC8n0xiifUwdec7g3kcGjCri6vTxaa8p6S3Fyyt2DxXccpi3Se4d_3mEQBZwMchKbQsw-W7Wj7njUk31ycgPQovvF4WrTuEYmhYw1sO9jCTORHmsSO7Shml7kv7AxlIUmzB2oq2KSmBhJV38Nz9oYj3KlPoMjgaIl4xYldNqnGyshh6fQyUQ1gQMQV6e4M5ro8YthjPOCvAT8yk77dTyOoE6Im58cAp6KtM-Gko-tWppUQTu-0M82LOvD_duP77n-hcoTw

Decoded JWT token header:

{ "kid": "985b2d4d-d215-407c-8716-5523604bc4e2", "alg": "RS256" }

Decoded JWT token payload:

  "sub": "1234567890",
  "name": "EXAMPLE TOKEN",
  "iat": 1516239022,
  "nbf": 1686137024,
  "exp": 1717673024

JWT Token expiration

To ensure the validity of JWT tokens and prevent the use of expired tokens, the inclusion of the following claims is required:

  • NBF (Not Before)

    • The "nbf" claim specifies the earliest time at which the token can be considered valid. Tokens with a "nbf" claim set in the future should not be accepted.
  • EXP (Expiration Time)

    • The "exp" claim defines the expiration time of the token. Tokens with an "exp" claim set in the past should not be accepted.

Request authentication

During the process of request authentication, the coinapi server follows a series of steps to ensure secure access to its resources. Here's an overview of the authentication process:

  1. Upon receiving the request, the coinapi server extracts the JWT from Authorization header.
  2. Then, it verifies JWT signature and checks the "NBF" and "EXP" claims to ensure token validity and expiration.
  3. If the JWT is valid and not expired, the server authorizes the request and proceeds with the necessary processing to access coinapi resources.
  4. If the JWT is invalid or expired, the server returns an appropriate error response.

TLS Client Cert

TLS Client Certificate acquired from the Managed Cloud REST API (/v1/certificate/pem endpoint) provided while establishing a TLS session with us.


This method of authentication is FIX protocol specific. Exact message that needs to be sent to us will be described in the documentation of the specific API protocol Logon (35=A) message page.

AWS Signature Version 4

AMAZON S3 uses Authorization request header to provide authorization information. The value for this header must follow spcific pattern described as AWS Signature Version 4 (opens in a new tab).

Example below shows Authorization header value compliant with AWS Signature Version 4.

Please note that Credential string contains our apikey as access-key-id. Assuming that your API key is 73034021-THIS-IS-SAMPLE-KEY, then the authorization header you should send to us will look like:

Authentication: AWS4-HMAC-SHA256 Credential=73034021-THIS-IS-SAMPLE-KEY/20211203/us-east-1/s3/aws4_request, SignedHeaders=host; Signature=65e655c69da9906ac6076a28f75d9e4947aaed3be1f419757a3a84e24662673d

Although AWS Signature Version 4 is very strict about each of the signature components, our API takes only our apikey value into account.

Copyright 2022 COINAPI LTD or its affiliates. All rights reserved.