Authentication

Setting up access to the Sypht API

This guide covers the setup and configuration of access credentials for working with the Sypht API.

API requests with Sypht are authenticated using the industry-standard OAuth2 authentication protocol. This authorization flow has three basic steps:

Obtain your Client ID and Client Secret from the Sypht admin console
Generate a temporary access token via the authentication endpoint
Supply this token alongside subsequent API requests

Tokens are generated on demand and should be reused by API Clients for up-to the 60 minute token expiry limit. Tokens can then be regenerated as required for long-running tasks.

API Credentials generated before the 16th June, 2020 are marked as legacy credentials in the Sypht administration console. These credentials may only used with the legacy authentication endpoint.

Setting up credentials

To access the Sypht API, first obtain a credential pair from the company administration console.

Within the Sypht application, open the settings cogs and select "My API Credentials".

An API Credential pair is generated by default on all accounts. You may create one or more alternative credential pairs, expire old credentials or rotate secrets from this screen.

Generating an authentication token

Access tokens are obtained by sending a POST request to the authentication endpoint (https://auth.sypht.com/oauth2/token) with your encoded client ID and secret.

The following python sample function returns an authentication token given a client ID and secret.

import requests

from base64 import b64encode

def authenticate(client_id, client_secret):
    endpoint = "https://auth.sypht.com/oauth2/token"
    audience = "https://api.sypht.com"
    basic_auth_slug = b64encode((client_id + ":" + client_secret).encode("utf-8")).decode(
        "utf-8"
    )
    result = requests.post(
        endpoint,
        headers={
            "Accept": "application/json",
            "Content-Type": "application/x-www-form-urlencoded",
            "Authorization": f"Basic {basic_auth_slug}",
        },
        data=f"client_id={client_id}&grant_type=client_credentials",
        allow_redirects=False,
    ).json()

    if result.get("error"):
        raise Exception("Authentication failed: {}".format(result["error"]))

    return result["access_token"]

Authenticating requests

Subsequent requests to the Sypht API are authenticated by supplying the generated access token in the Authorization header in the format Bearer <accesstoken>

The following python sample function constructs an authenticated request to return results for an uploaded file given the file_id and access_token .


def get_results(file_id, access_token):
    endpoint = "https://api.sypht.com/result/final/{file_id}"
    headers = {
        "Authorization": "Bearer " + access_token,
        "Accept": "application/json",
        "Content-Type": "application/json"
    }

    return self.requests.get(endpoint, headers=headers).json()

API Clients

These authentication examples are adapted from the open-source Sypht Python Client on GitHub.

We maintain API clients and code samples in a variety of languages including:

Python (link)
C# (link)
Node (link)
Java (link)

See the sypht-team repository for a full listing. Contributions of functionality, language support or documentation are always warmly welcomed!

PreviousIntroduction NextUpload and Extract (v2)

Last updated 3 years ago

import requests from base64 import b64encode def authenticate(client_id, client_secret): endpoint = "https://auth.sypht.com/oauth2/token" audience = "https://api.sypht.com" basic_auth_slug = b64encode((client_id + ":" + client_secret).encode("utf-8")).decode( "utf-8" ) result = requests.post( endpoint, headers={ "Accept": "application/json", "Content-Type": "application/x-www-form-urlencoded", "Authorization": f"Basic {basic_auth_slug}", }, data=f"client_id={client_id}&grant_type=client_credentials", allow_redirects=False, ).json() if result.get("error"): raise Exception("Authentication failed: {}".format(result["error"])) return result["access_token"]

def get_results(file_id, access_token): endpoint = "https://api.sypht.com/result/final/{file_id}" headers = { "Authorization": "Bearer " + access_token, "Accept": "application/json", "Content-Type": "application/json" } return self.requests.get(endpoint, headers=headers).json()