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

# Auth

Use this endpoint to hold FanCash to be spent for a single user. This must be followed by a FanCash Capture API call for the auth to complete the FanCash spend process.

## Preconditions

* **You must know the Account Tenant FanID for the user's account, this value is a property of the ID Token returned in the SSO login process.** It is possible to store and re-use this value for the user.
* This API requires either a server-to-server or user access auth token:
* You can generate a server-to-server token using the [S2S Auth API](https://api.docs.fan/s2s/s2s-auth)
* User access tokens are returned from the [Code Exchange](https://api.docs.fan/sso/code-exchange) step of the SSO auth process.

### Required Scopes

`fancash:auth`

## Request

### URL

`/v1/{account_tenant_fanid}/auth`

### Path Parameters

| Name                   | Description                                                                                                                                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_tenant\_fanid | unique identifier representing the user in a non-Fanatics system as a proxy for their internal fanatics id. Each vendor will have their own account\_tenant\_fan\_id for a user. This value is a property of the ID Token returned in the SSO login process. |

### Headers

| Name          | Description                                                                         |
| ------------- | ----------------------------------------------------------------------------------- |
| Authorization | either a user Bearer token or a server-to-server Bearer token for accessing the API |

### Data

#### Request Object

<table><thead><tr><th width="214">Name</th><th width="102" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>amount</td><td>true</td><td>dollar amount of FanCash written as a string NOT a number. supports fractional dollar amounts up to six decimal places</td></tr><tr><td>currency</td><td>true</td><td>ISO currency code for the FanCash issuance. Only USD is supported for now. Please pass USD only.</td></tr><tr><td>external_reference_id</td><td>true</td><td>unique identifier for this transaction within the systems of the caller of the API. If you have a unique id (ideally a uuid) on your side for this transaction you should use that (order id for example). If not, It is recommended to generate and store a uuid for your own records and to add this uuid to the request in this field. Please note, we use this id for idempotency. If you send the same id more than once it will be rejected.</td></tr><tr><td>country_code</td><td>false</td><td>country of the jurisdiction in which the FanCash is being earned written as a 3-character ISO 3166 country code.</td></tr><tr><td>subdivision</td><td>false</td><td>political subdivision of the country of jurisdiction in which the FanCash is being earned written as a 2-character abbreviation. Within the United States of America, this would be the 2 character abbreviation of the particular State. For example, NY for New York.</td></tr><tr><td>test_transaction</td><td>false</td><td>indicates whether this transaction is for testing purposes only. True for a test, False if a normal non-test transaction</td></tr></tbody></table>

## Response

### Normal Response Data

| Name                    | Description                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| external\_reference\_id | the external\_reference\_id from the request used for correlating this transaction to partner systems |
| auth\_transaction\_id   | unique identifier for the FanCash auth transaction within the Fanatics system.                        |

### Error Response Data

#### Error Response Wrapper

| Property  | Description                                                                                                                                                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| errors    | array containing error response entries                                                                                                                                                                                              |
| rc        | randomly generated identifier allowing call tracing within Fanatics. When reporting repeated errors or coordinating issue resolution with Fanatics, this value will assist in diagnosing any issues.                                 |
| timestamp | processing timestamp in Zulu time of Fanatics API server using ISO 8601 format (<https://datatracker.ietf.org/doc/html/rfc3339#section-5.6>). Useful for issue resolution with Fanatics as log data is partitioned by date and time. |

#### Error Response Wrapper -> Errors -> item

| Property | Description                                                                                                                          |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| code     | Fanatics error code for the specific error; this is generally not an http status code. Code values are generally stable for the API. |
| message  | additional textual information describing the error. This is useful in debugging, but should not be checked programmatically         |

## Full Spec

{% openapi src="/files/EJyvdHzZr0CInDICbxQF" path="/v1/{account\_tenant\_fanid}/auth" method="post" %}
[openapi-loyalty.yaml](https://437278376-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdwQzxiD8zGmLqqQUA0qE%2Fuploads%2Fgit-blob-894098b3d5714cd455f740283c034ac7877d7753%2Fopenapi-loyalty.yaml?alt=media)
{% endopenapi %}