> ## Documentation Index
> Fetch the complete documentation index at: https://docs.symmetry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication in SPF

> Authenticate SPF Hosted, On-Premise, and API clients for secure requests. Covers basic auth, OAuth 2.0 postbacks, JWT access tokens, and API key headers.

This page covers two separate authentication schemes, depending on how you use SPF:

* [SPF Hosted & On-Premise](#spf-hosted-and-on-premise): basic authentication for outbound webservice proxy calls, or OAuth 2.0 to authenticate SPF's postback requests to your server
* [SPF API](#spf-api): JWT-based authentication for every API request

## SPF hosted & on-premise

For SPF Hosted & On-Premise, there are two types of authentication used within SPF: basic authentication and OAuth 2.0 authentication (either with client credentials or a password). You can also choose to use neither.

SPF supports basic authentication for proxy endpoints and OAuth 2.0 authentication for target endpoints used to receive postback data from SPF.

### Basic authentication

To use basic authentication in the schema for proxy endpoints, set the `"authType"` value to `"BASIC"` within the nested `webservice.proxy.authentication` element for the [SPF Registration](/spf/hosted-and-on-premise/registration).

Sample SPF Registration:

```text theme={null}
"webservice": {
            "enabled": true,
            "continueIfUnsuccessful": true,
            "useNormalizedAddress": true,
            "showNormalizedAddressNotes": true,
            "proxy": {
                "authentication": {
                    "authType": "BASIC",
                    "username": "{ ENTER USERNAME HERE }",
                    "password": "{ ENTER PASSWORD HERE }"
                },
                "host": "{ ENTER PROXY HOST HERE }",
                "port": "{ ENTER PROXY PORT HERE }"
            }
        }
```

### OAuth 2.0: Client credentials

To use OAuth 2.0 authentication using grant type client credentials in the schema for postback data, configure your [SPF Registration](/spf/hosted-and-on-premise/registration):

* Set the `"authType"` value to `"OAUTH2"`
* Set the `"oauth2GrantType"` value to `"CLIENT_CREDENTIALS"`
* Set the `"oauth2ClientId"` value to your OAuth 2.0 client ID
* Set the `"oauth2ClientSecret"` value to your OAuth 2.0 client secret

Sample SPF Registration:

```text theme={null}
"postback": {
            "target": {
                "url": "https://spf.symmetry.com:443/spf/postback-receive",
                "authentication": {
                    "authType": "OAUTH2",
                    "oauth2GrantType": "CLIENT_CREDENTIALS",
                    "oauth2AuthServerUrl": "{ ENTER OAUTH AUTH TOKEN SERVER URL HERE }",
                    "oauth2ClientId": "{ ENTER CLIENT ID HERE }",
                    "oauth2ClientSecret": "{ ENTER CLIENT SECRET HERE }"
                }
            },
            "encryption": {
                "enabled": false
            },
            "failureNotificationEmail": "{ POSTBACK FAILURE NOTIFICATION EMAIL }"
        }
```

### OAuth 2.0: Grant type password

To use OAuth 2.0 authentication using grant type password credentials in the schema for postback data, configure your [SPF Registration](/spf/hosted-and-on-premise/registration):

* Set the `"authType"` value to `"OAUTH2"`
* Set the `"oauth2GrantType"` value to `"PASSWORD"`
* Set the `"oauth2ClientId"` value to your OAuth 2.0 client ID
* Set the `"oauth2ClientSecret"` value to your OAuth 2.0 client secret
* Set the `"username"` value to your OAuth 2.0 username
* Set the `"password"` value to your OAuth 2.0 password

Sample SPF Registration:

```text theme={null}
"postback": {
            "target": {
                "url": "https://spf.symmetry.com:443/spf/postback-receive",
                "authentication": {
                    "authType": "OAUTH2",
                    "oauth2GrantType": "PASSWORD",
                    "oauth2AuthServerUrl": "{ ENTER OAUTH AUTH TOKEN SERVER URL HERE }",
                    "oauth2ClientId": "{ ENTER OAUTH CLIENT ID HERE }",
                    "oauth2ClientSecret": "{ ENTER OAUTH CLIENT SECRET HERE }",
                    "username": "{ ENTER OAUTH USERNAME HERE }",
                    "password": "{ ENTER OAUTH PASSWORD HERE }"
                }
            },
            "encryption": {
                "enabled": false
            },
            "failureNotificationEmail": "{ ENTER POSTBACK FAILURE NOTIFICATION EMAIL HERE }",
            "proxy": {
                "authentication": {
                    "authType": "BASIC",
                    "username": "{ ENTER PROXY BASIC AUTH USERNAME HERE }",
                    "password": "{ ENTER PROXY BASIC AUTH PASSWORD HERE }"
                },
                "host": "{ ENTER PROXY HOST HERE }",
                "port": "{ ENTER PROXY PORT HERE }"
            }
        }
```

## SPF API

SPF API endpoints use a JWT token for authentication and authorization. An authentication endpoint is available that will accept your product API Key or Hash and provide a valid JWT token.

To request a new JWT access token, make an HTTP GET request to the URL below, setting the api-key header to the API Key or Hash provided by Symmetry. The JWT access token will expire after 24 hours.

Cache the token rather than requesting a fresh one per call, and refresh it on expiry.

Authentication URL: `https://api.symmetry.com/authentication/login`

Sample Authentication GET Request:

```text theme={null}
curl --location --request GET 'https://api.symmetry.com/authentication/login' \
--header 'Accept: application/json' \
--header 'api-key: y0urAPI-KeyG0esH3re'
```

A successful authentication endpoint response will contain a JSON object with an access token that can be used for API requests.

Sample successful Authentication response:

```json theme={null}
{
  "accessToken": "yoUrTokEnISh3re!"
}
```

The encrypted JWT token is to be included in each request to the SPF-API as a **Bearer token** in the **Authorization** header with the following formatting:

`Authorization: Bearer eyJhbGciOiJSU0EtT0FF...`

Authorization header sample:

```text theme={null}
curl --location --request GET 'https://api.symmetry.com/spf/getPdf/W4101' \
--header 'Accept: application/pdf' \
--header 'Authorization: Bearer yoUrTokEnG0esH3re!'
```