# Overview & Authentication

### Base URL

All API requests are made to:

```
https://auxvyn.com/api/v1
```

***

### Authentication

Every request to the Auxvyn API must include your API key in the request header. Requests without a valid key are rejected with a `401 Unauthorized` response.

#### Header format

```
x-api-key: auxvyn_your_key_here
```

#### Example request

```lua
local HttpService = game:GetService("HttpService")

local response = HttpService:RequestAsync({
    Url = "https://auxvyn.com/api/v1/ping",
    Method = "GET",
    Headers = {
        ["Content-Type"] = "application/json",
        ["x-api-key"] = "auxvyn_your_key_here",
    },
})
```

{% hint style="info" %}
In practice you never write raw HTTP requests like this. The Auxvyn Lua module handles all of this for you automatically. This is just to show how authentication works under the hood.
{% endhint %}

***

### How Keys Are Verified

When a request arrives at the Auxvyn API:

1. The `x-api-key` header is read
2. The key is hashed with SHA-256
3. The hash is looked up in the database
4. If a matching, non-revoked key is found, the workspace it belongs to is identified
5. The request is processed against that workspace's data only

This means:

* Your raw key is never stored — only the hash
* A key can only ever access the workspace it was generated for
* Revoked keys are rejected instantly

***

### Request Format

All requests that include a body send JSON:

```
Content-Type: application/json
```

All responses are JSON.

***

### Response Format

Every response from the Auxvyn API follows the same structure:

#### Success

```json
{
  "success": true,
  "data": { ... }
}
```

#### Error

```json
{
  "success": false,
  "error": "A human-readable error message"
}
```

***

### Status Codes

| Code  | Meaning                                                               |
| ----- | --------------------------------------------------------------------- |
| `200` | Request succeeded                                                     |
| `400` | Bad request — missing or invalid fields                               |
| `401` | Unauthorized — missing or invalid API key                             |
| `403` | Forbidden — your key doesn't have access to this resource             |
| `404` | Not found — the requested resource doesn't exist                      |
| `409` | Conflict — for example trying to create something that already exists |
| `429` | Rate limited — too many requests                                      |
| `500` | Internal server error — something went wrong on Auxvyn's end          |

***

### Rate Limiting

The Auxvyn API is rate limited to protect the platform and ensure fair usage for all developers.

| Plan | Requests per 10s |
| ---- | ---------------- |
| Free | 60               |
| Pro  | 300              |

If you exceed the rate limit you will receive a `429 Too Many Requests` response. Your requests will be accepted again once the rate limit window resets.

{% hint style="danger" %}
The Auxvyn Lua module does not currently implement automatic retry on rate limit errors. If you are hitting rate limits frequently, reduce how often you are calling `set()` — for example by batching saves on player leave instead of saving on every value change.
{% endhint %}

***

### Endpoints

Here is a summary of all available endpoints:

| Method | Endpoint                 | Description                           |
| ------ | ------------------------ | ------------------------------------- |
| `GET`  | `/api/v1/ping`           | Verify your connection and API key    |
| `GET`  | `/api/v1/data`           | Get one or all values for a player    |
| `POST` | `/api/v1/data/set`       | Set a value for a player              |
| `POST` | `/api/v1/data/increment` | Increment a numeric value             |
| `POST` | `/api/v1/data/delete`    | Delete a key or all data for a player |

Each endpoint is documented in detail in the following pages.

***

### Using the Lua Module vs Raw API

You rarely need to call the API directly. The Auxvyn Lua module wraps every endpoint in a clean function:

| Raw API                       | Lua Module                         |
| ----------------------------- | ---------------------------------- |
| `GET /api/v1/ping`            | `Auxvyn.ping()`                    |
| `GET /api/v1/data`            | `Auxvyn.get()` / `Auxvyn.getAll()` |
| `POST /api/v1/data/set`       | `Auxvyn.set()`                     |
| `POST /api/v1/data/increment` | `Auxvyn.increment()`               |
| `POST /api/v1/data/delete`    | `Auxvyn.delete()`                  |

The module handles authentication, error handling, JSON encoding and decoding, and response parsing automatically.

{% hint style="warning" %}
**Important:** Calling the Auxvyn API from outside of Roblox is strictly against our Terms of Service. This includes calling the API from external scripts, tools, bots, Postman, or any other non-Roblox environment. Violations are automatically detected and will result in an immediate permanent IP ban with a strict appeal process.
{% endhint %}

***

### What's Next


---

# 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://auxvyn.gitbook.io/auxvyn-docs/api-reference/overview-and-authentication.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.