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

# Authentication

## Session-Based Authentication

Turbine authenticates users with sessions. The session ID arrives in a `Set-Cookie` response header. Send `id=<SESSION_ID>` as a cookie with each subsequent request.

{% hint style="success" %}
The [Typescript SDK](https://github.com/propeller-heads/turbine-sdk) handles authentication automatically.

The authentication flow below is implemented in [`TurbineClient.ensureAuthenticated()`](https://github.com/propeller-heads/turbine-sdk/blob/main/src/turbineClient.ts#L1057).
{% endhint %}

## Check Authentication Status

Make a GET request to `/api/me` (see the [Swagger UI](https://api.turbine.exchange/api/swagger-ui/)). Include the session ID in a `Cookie` header if you have one.

```bash
curl 'https://staging-api.turbine.exchange/api/me' \
  -H 'content-type: application/json' \
  -b 'id=<SESSION_ID>'
```

A `200 OK` response means you are authenticated.

A `401 Unauthorized` response means you must authenticate.

## Authenticate

{% stepper %}
{% step %}
**Get nonce**

Make a POST request to `/api/nonce` (see the [Swagger UI](https://api.turbine.exchange/api/swagger-ui/)).

```bash
curl 'https://staging-api.turbine.exchange/api/nonce' \
  -X 'POST'
```

The response contains a nonce, for example:

```bash
"uE6LoICEKw01JjApm"
```

{% endstep %}

{% step %}
**Sign a SIWE message**

Turbine uses the [Sign-In With Ethereum](https://login.xyz/) (SIWE) standard.

Sign a specific message containing the nonce with your Ethereum wallet.

The message format is:

```
app.turbine.exchange wants you to sign in with your Ethereum account:
<YOUR_WALLET_ADDRESS>

Sign in to Turbine with your Ethereum wallet

URI: https://api.turbine.exchange/api
Version: 1
Chain ID: 1
Nonce: <YOUR_NONCE>
Issued At: <TIMESTAMP>
```

{% endstep %}

{% step %}
**Verify the signature**

Make a POST request to `/api/verify` (see the [Swagger UI](https://api.turbine.exchange/api/swagger-ui/)).

The body must contain the signed message and the signature:

```json
{
    "message": "...message with newlines represented as \n...",
    "signature": {
        "r": "0x...",
        "s": "0x...",
        "yParity": "0x...",
        "v": "0x..."
    }
}
```

If verification passes, the response includes a `Set-Cookie` header with session ID `id=...`.
{% endstep %}
{% endstepper %}

## Make an Authenticated Request

Include a `Cookie` header with `id=<YOUR_SESSION_ID>` in subsequent requests. For example, check your authentication status again with `/api/me`.

## Session Expiration

A session is valid for 5 minutes.

Keep it active by making authenticated requests before it expires, for example by calling `/api/me`. Each call before expiration extends the session by another 5 minutes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://docs.turbine.exchange/reference/api/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.