Quickstart & Authentication
Authenticate with the Depa API and make your first authenticated request.
Every request to the Depa API is authenticated with a token in the Authorization header. The
token is either:
- an API key, which Depa issues for server-to-server integrations, or
- a user token (a JWT) that you get by signing in, for actions taken on behalf of a person, such as approving a payment.
1. Obtaining a User Token
If you have an API key, skip to step 2. Otherwise, sign in with your Depa user's credentials:
Request
curl -X POST https://api.sandbox.depa.finance/v1/sign_in \
-H "Content-Type: application/json" \
-d '{
"email": "developer@yourcompany.com",
"password": "your_secure_password"
}'If two-factor authentication is enabled for the user, add the current code from their authenticator app as "otp_attempt".
Response
{
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3V1aWQiOiI3ZGU4OWQ2Mi0xNjBiLTRkMTItYTdiMS1kM2IzYWM4MmM5MTAiLCJtYWluX2FjY291bnRfdXVpZCI6ImMxMmU3MzE3LTcyYzctNDFjNy1iMmFjLTJkMGI3NmYyMzUwYyIsInJvbGVzIjpbIm1haW4iLCJzZXBhIiwidHJhbnNhY3Rpb25fbW9uaXRvcmluZyJdLCJleHAiOjE3NzU0ODc5NTN9.signature"
}
}The token is a JWT. Its payload contains your user's UUID, your main account's UUID, your roles,
the vaults you can access and the expiry time (exp).
2. Authenticating Requests
Send the API key or user token as the raw value of the Authorization header, with no
Bearer prefix:
Authorization: <your_token>No Bearer prefix
Depa reads the whole header value as the token. Authorization: Bearer <token> fails with
401 You are not authenticated.
User tokens expire, and stop working early if they're revoked or the user's password changes.
When a request returns 401, sign in again. A 403 means the token is valid but its user isn't
allowed to do that: reading needs the api_read role and changes need api_write.
3. Your First API Call
Once authenticated, fetch the accounts linked to your client entity:
cURL
curl -X GET https://api.sandbox.depa.finance/v1/accounts \
-H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI..." \
-H "Accept: application/json"Node.js / TypeScript
const BASE_URL = "https://api.sandbox.depa.finance/v1";
async function getAccounts(token: string) {
const response = await fetch(`${BASE_URL}/accounts`, {
method: "GET",
headers: {
Authorization: token,
Accept: "application/json",
},
});
if (!response.ok) {
throw new Error(`API Error: ${response.status} ${response.statusText}`);
}
const data = await response.json();
return data;
}Python
import requests
BASE_URL = "https://api.sandbox.depa.finance/v1"
def list_accounts(token: str):
headers = {
"Authorization": token,
"Accept": "application/json",
}
response = requests.get(f"{BASE_URL}/accounts", headers=headers)
response.raise_for_status()
return response.json()Entity Concepts
When integrating Depa, you will interact with three core abstractions:
- Client: The primary business contract holding one or more accounts and users.
- User: An individual, machine, or service account that signs in and executes actions within granted permission scopes.
- Account: An ownership unit that holds fiat bank accounts (IBANs), blockchain wallets, sub-accounts, and ledger balances.