Authentication

There are two sorts of keys in the dfuse ecosystem:

  1. A long-lived API key, which will resemble server_abcdef123123123000000000000000000, used to generate short-lived JWT.
  2. A short-lived JWT, used when performing any call on the dfuse Platform, which will resemble: eyJhbGciOiJLTVNFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTYxMzI4MjAsImp0aSI6IjQwNWVmOTUxLTAwZTYtNGJmNC1hZWMxLTU0NTU1ZWMzMTUwMiIsImlhdCI6MTU1NjA0NjQyMCwiaXNzIjoiZGZ1c2UuaW8iLCJzdWIiOiJ1aWQ6MHdlbnU2NmUwNzU4OWRhODY4MWNlIiwiYWtpIjoiM2NhYWEzYzA3M2FlZjVkMmYxOGUwNjJmZDkzYzg3YzMzYWIxYzA1YzEzNjI3NjU2OTgzN2Y5NDc5NzZlMjM0YSIsInRpZXIiOiJmcmVlLXYxIiwic3RibGsiOi0zNjAwLCJ2IjoxfQ.000HeTujIuS_LRvvPN6ZRCmtoZqZyV6P1enNBviwK8v7Tf7BLHJIrEpQoEREKSIMdZWPrMQl_OE55yJP0MxUDA

Obtaining a Long-Lived API Key

Once you have created an account through the dfuse portal you will be able to obtain an API key.

Click on “GENERATE NEW KEY” and you’ll now be able to start customizing your key for your specific needs. First assign the API key a name so that you’ll be able to differentiate it from other API keys that you generate. Then, select the key-type between mobile, web, or server. * Mobile - adaptive rate limiting to ensure abuse prevention. The rate limiting thresholds will eventually be controllable by yourself. Mobile can handle a large number of IPs, with more granular rate limiting by IP. * Web - adaptive rate limiting to ensure abuse prevention. The rate limiting thresholds will eventually be controllable by yourself. JWTs generated by a Web key will be scoped to a small number of IPs, with heavy limiting of calls per IP. Web keys will have their Origin header verified to help with abuse prevention. * Server - Should be used for server-to-server data access. Aggressive rate limiting for JWT issuance, as the generated tokens should be cached and used for their lifespan. Accepts a large number of calls per IP.

For ease of identification, all keys will be prefixed by their key type. Mobile and web keys are safe to publish within your mobile or web application.

Obtaining a Short-Lived JWT

Once you have this API key, call the https://auth.dfuse.io/v1/auth/issue endpoint to obtain a fresh Authentication Token using the following command. Do not forget to replace the API key by your own!


curl https://auth.dfuse.io/v1/auth/issue -s --data-binary '{"api_key":"web_abcdef12345678900000000000"}'

{       
  "token":"eyJhbGciOiJLTVNFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTYxMzI4MjAsImp0aSI6IjQwNWVmOTUxLTAwZTYtNGJmNC1hZWMxLTU0NTU1ZWMzMTUwMiIsImlhdCI6MTU1NjA0NjQyMCwiaXNzIjoiZGZ1c2UuaW8iLCJzdWIiOiJ1aWQ6MHdlbnU2NmUwNzU4OWRhODY4MWNlIiwiYWtpIjoiM2NhYWEzYzA3M2FlZjVkMmYxOGUwNjJmZDkzYzg3YzMzYWIxYzA1YzEzNjI3NjU2OTgzN2Y5NDc5NzZlMjM0YSIsInRpZXIiOiJmcmVlLXYxIiwic3RibGsiOi0zNjAwLCJ2IjoxfQ.000HeTujIuS_LRvvPN6ZRCmtoZqZyV6P1enNBviwK8v7Tf7BLHJIrEpQoEREKSIMdZWPrMQl_OE55yJP0MxUDA",
  "expires_at":1556132820
}

Our client-JS library will handle the token issuance and caching for you if you decide to utilize it. You can also consult a working reference example if you would like to follow along with some sample TypeScript code.

Tip

To learn more about JWTs, you can consult https://jwt.io/introduction/.

Each JWT is valid for a period of 24 hours. Make sure to cache those values to avoid hitting rate limiting on JWT issuance. A connection will be validated upon a valid connection being made and will not need to be reauthenticated until a new connection needs to be reestablished.

Lifecycle of Short-Lived JWTs

Each JWT has an expiration date, so it is important to take that into account before making a request to the dfuse APIs. Here is the recommended procedure to take before making a request:

  1. Retrieve the JWT, and examine it’s expiration time
  2. If the JWT is past its expiration time, is near expiration, or is absent from cache, fetch a new one through the /v1/auth/issue endpoint, and cache the response.
  3. Call dfuse with the valid JWT token.

Each time you get a fresh JWT, it contains the updated expiration time and the token itself.

Tip

Reminder: Once a connection is established, it will not be closed if the JWT expires during the session.

REST Authentication

To achieve authentication over REST, specify the Authorization: Bearer [token] header in the HTTP request. See more details.


eosc -H "Authorization: Bearer YOURTOKENHERE" -u https://mainnet.eos.dfuse.io [ ... ]

Don’t forget to replace the token in the above command with a valid JWT, retrieved using /v1/auth/issue

WebSocket Authentication

This example uses the https://github.com/hashrocket/ws command-line WebSocket program. To authenticate with query string, use this code:


ws -o https://b2b.dfuse.io wss://mainnet.eos.dfuse.io/v1/stream?token=YOURTOKENHERE

With browser-based WebSocket connections, it is not possible to specify additional headers. In this situation, pass your JWT as the token query string parameter.

You can pass the token query string parameter to authenticate REST or WebSocket requests.

The Origin Header

When the Origin header is present in a WebSocket connection, it must match the origin provided in your API header key.

An Origin HTTP request header (ex. Origin: https://yourcompany.com) is mandatory when initiating a WebSocket connection. A 403 error will be returned otherwise.

The Origin header will be enforced on all web keys. As the Origin header becomes enforced, it will need to match the origin you registered along with your API key identity.

GraphQL Authentication

Using the apollo-client websocket protocol, the INIT message should contain an Authorization key, with the same format as the REST authentication (bearer token).

When doing POST calls to the /graphql endpoint, you must specify the Authorization header, exactly like any other REST calls.

GraphQL over gRPC Authentication

Using the language of your choice, use the OAuth2 authentication method with gRPC. Set the OAuth2 Access Token to be your JWT, and if required, specify Bearer as the method, then proceed normally. This will set the authorization gRPC header, similiar to the HTTP header of the same name.