Authentication

Overview

ethos provides three methods of authentication:

Private key authentication

All /api endpoints use API private keys to authenticate requests. If you do not use an API key for your requests, or if you use a key from the wrong account, your call will return an error. A 400 error indicates an invalid or missing API key.

Public key authentication

All /client endpoints use a public API key.

OAuth

If you are a tech partner integrating, we recommend using OAuth to authenticate your app. OAuth offers multiple benefits over a private key integration, including security, usability, and improved rate limits.

API key scopes

The ethos API supports the industry-standard use of API scopes, which allow you to restrict access for third parties using a private API key. Adding a scope helps you protect your and your customers’ data by limiting what third parties can access.

You can add any of the following scopes to any new private API key:

• Read-only Only allows third parties to view all data associated with the endpoint
• Full Allows third parties to create, delete, or make changes to anything associated with that endpoint
• Custom Allows you to decide how much access to give the third party

Note that you cannot add a scope to an existing private key, which have full access by default. You also cannot edit a private API key after it’s been created. If you need to remove access to a key based on its current scope, delete it and then create a new key with the correct scope.

Private key authentication

Private key authentication for /api endpoints is performed by setting the following request header:

Authorization: Ethos-API-Key your-private-api-key