> For the complete documentation index, see [llms.txt](https://docs.sypht.com/sypht/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sypht.com/sypht/setup/api-credentials.md).

# Authentication

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](https://oauth.net/2/) authentication protocol. This authorization flow has three basic steps:

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

{% hint style="info" %}
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.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

### 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".

![](/files/-ML5ibEYFo6R8xauAtiW)

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.

![](/files/-ML5jogyw687kPchVo0-)

### 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.

```python
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` .

```python

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](< https://github.com/sypht-team/sypht-python-client>))
* C# ([link](https://github.com/sypht-team/sypht-csharp-client))
* Node ([link](https://github.com/sypht-team/sypht-node-client))
* Java ([link](https://github.com/sypht-team/sypht-java-client))

See the [sypht-team](https://github.com/sypht-team) repository for a full listing. Contributions of functionality, language support or documentation are always warmly welcomed!