Authenticating with the API

How to get a JWT to use with the API.
Tags:

What is a JWT?

Citing https://jwt.io/introduction :

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

A JWT (often referred to as simply a token, or bearer token), lets you securely interact with an API without having to send the login information for each operation, which is more secure in general. However, the token expires and must be renewed when it does.

How to obtain a JWT?

You need to make a POST request to the API, the body of the request should be a JSON object that contains the username and password.

Here’s an example in python, using the requests library:

import requests

API_BASE_URL = "https://api.shapeshift3d.com"

def authenticate(username, password):
    """Login a user: get a JWT from the API, authenticating using a USERNAME and PASSWORD

    Args:
        username (str): The email of the user to authenticate
        password (str): _description_

    Returns:
        str: the bearer token
    """
    response = requests.post(f'{API_BASE_URL}/v1/auth/login',
                             {
                                 'username': username,
                                 'password': password
                             })
    response.raise_for_status()
    auth = response.json()
    token = auth['accessToken']
    return token

How to use the token?

To make any requests to the API, the token must be added to the HTTP header Authorization.

Here’s an example in python, using the requests library:

import requests

def make_authorization_header(token):
    """Create a dict that contains the HTTP authorization header

    Args:
        token (str): The authorization header

    Returns:
        dict: The dictionary containing the HTTP authorization header
    """
    return {"Authorization": f"Bearer {token}"}

# Get the JWT
token = authenticate(username, password)

# Make a request
response = requests.get(url, headers=make_authorization_header(token))

# Raise an exception if the request failed
response.raise_for_status()