Authentication

Should I be authenticated to use the REST API? Which endpoints require authentication? How to authenticate?

Since Akord

As a user of Akord's REST API, you may authenticate using the following methods:

• JSON Web Tokens – short-lived tokens

• API keys - long life, revokable keys

Both authentication methods are working interchangeably. Choosing the authentication method depends of your use case. It is not recommended to use personal API key on customer facing client-side apps (eg, your frontend app that possibly requires Akord storage) because of the risk of compromising the key.

JSON Web Tokens

You may issue Jason Web Tokens (JWT) using your credentials but not with a simple password grant. Instead, we promote Secure Remote Protocol (SRP), which prevents the password from leaving your machine. Since SRP is little bit more demanding for client negotiating tokens we encapsulate the SRP client-side logic in CLI.

Future releases of this doc may bring pure HTTP token negotiation.

Prerequisite

npm i -g @akord/akord-cli

Issue new token

This shows as well how to call the CLI from from a non-shell env

Bash

akord login <akord_account_email> -p <akord_account_password> -t

JavaScript

const { spawn } = require('child_process');

const command = 'akord';
const args = ['login', email, '-p', password, '-t'];

const process = spawn(command, args);

process.stdout.on('data', (data) => {
  console.log('JWT:', data.toString());
});

process.stderr.on('data', (data) => {
  console.error('Error:', data.toString());
});

Python

import subprocess

command = ['akord', 'login', email, '-p', password, '-t']
process = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
stdout, stderr = process.communicate()

print("JWT:", stdout.decode())
print("Error:", stderr.decode())

Use the token

Put the JWT, prefixed with Bearer into Authorization header of HTTP request to REST API, for example:

Bash

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_token"
https://api.akord.com/storage-balance

JavaScript

const response = await fetch('https://api.akord.com/storage-balance', {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer your_jwt',
        'Content-Type': 'application/plain'
    }
})

Python

import requests

response = requests.get(
    url='https://api.akord.com/storage-balance', 
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer your_jwt',
        'Content-Type': 'applicaiton/json'
    }
)

API Key

Generate API Key

Typically, you would generate / rotate the API key using our frontend app: https://v2.akord.com/account/developers

You can also use the API directly to issue an API Key:

Bash

curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_token"
https://api.akord.com/api-keys

JavaScript

const response = await fetch('https://api.akord.com/api-keys', {
    method: 'PUT',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer your_jwt',
        'Content-Type': 'application/plain'
    }
})

Python

import requests

response = requests.put(
    url='https://api.akord.com/api-keys', 
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer your_jwt',
        'Content-Type': 'applicaiton/json'
    }
)

Use the API Key

Put the API Key into Api-Key header of HTTP request to REST API, for example:

Bash

curl -X GET \
-H "Content-Type: application/json" \
-H "Api-Key: your_api_key"
https://api.akord.com/storage-balance

JavaScript

const response = await fetch('https://api.akord.com/storage-balance', {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'application/plain'
    }
})

Python

import requests

response = requests.get(
    url='https://api.akord.com/storage-balance', 
    headers={
        'Accept': 'application/json',
        'Api-Key': 'your_api_key',
        'Content-Type': 'applicaiton/json'
    }
)