# Firstoken API

## API Reference

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://firstoken.gitbook.io/api-docs/api-reference/firstoken-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.