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

# Overview

These are the API docs for version 1 of Firstoken. API v1 is organized around REST. Our API allows developers to execute Tokenization functions via HTTPS client using TLS 1.2 protocol. The Firstoken API is a Web API that accepts JSON payloads and returns JSON-encoded responses and API key authentication.

{% hint style="info" %}
**Note**: The base URL is <https://api.firstoken.co/v1/>
{% endhint %}

{% hint style="warning" %}
Note: For testing in a sandbox environment, the URL is as follows: <https://api.firstoken-staging.co/v1/>
{% endhint %}

## Authentication <a href="#toc135036441" id="toc135036441"></a>

The Firstoken API uses an API key to authenticate requests. An API key is a token that a client provides when making API calls.

Your API keys carry many privileges, so make sure to keep them secure! Do not share your API keys in publicly accessible areas such as, client-side code, and so forth.

All API requests must be made over HTTPS TLS 1.2. Calls made over plain HTTP will fail. API requests without authentication will also fail. To get an API key you must sign in and go to the Keys section.

{% code title="POST /v1/account" %}

```
curl -X POST https://api.firstoken.co/v1/account \
-H 'x-api-key: YOUR_API_KEY' \
-H "Content-Type: application/json"
```

{% endcode %}

## IP Whitelist <a href="#toc135036442" id="toc135036442"></a>

For additional protection all requests must be made from a verified IP address. You can add a secure IP address to an API key in the key creation process. If you already have an API key created, you can edit it and add the addresses you need. To start associating secure IPs with an API key or creating a new API key from scratch and associating secure IP addresses you must sign in and go to the API section.

## Common response <a href="#toc135036443" id="toc135036443"></a>

Firstoken uses JSON-encoded responses. These responses maintain the same structure across all requests as follows:

<details>

<summary>Attributes</summary>

**status\_code**: *int*

The status code represents the result of the operation that was performed. For successful transactions a code 200 is always returned for the others another code is returned.// Some code

**status**: *string*

The status is a string result that only has two possible values. "Success" or "Fail".

**desc**: *string*

The desc value represents a short description about the status code.

**data**: *{object}*

The data variable represents the information expected from the request made. For success requests a JSON is returned. For failure requests an empty string is returned.

</details>

**EXAMPLE JSON RESPONSE STRUCTURE**

{% code fullWidth="false" %}

```json
{
    "status_code": 200,
    "status": success,
    "desc": "Success",
    "data": {}
}
```

{% endcode %}

## Status Codes <a href="#toc135036445" id="toc135036445"></a>

Firstoken uses different codes in its responses. You can see the meaning of each response code in the HTTP status code table.

| Code | Status  | Description                                                            |
| ---- | ------- | ---------------------------------------------------------------------- |
| 200  | Success | Success!                                                               |
| 400  | Fail    | Bad request. Expected request values are missing.                      |
| 403  | Fail    | Missing or incorrect authentication credentials. Ip whitelist missing. |
| 500  | Fail    | Something is broken. This is usually a temporary error.                |