# Sign in and start a session {#top}

**Session** · `POST /v1/sessions` · MCP tool `login`

Exchanges your login name and secret for a session. Send the session in the `X-Tarsana-Session` header on every later call. An API access token is not accepted here; after you sign in, you can create one with `issue-access-token`.

You do not need to sign in.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `login` | body | yes | Your login name |
| `secret` | body | yes | Your login secret |

## Returns

A JSON object with these keys: `session`, `login`, `scopes`, `tenants`, `expires_at`, `guarantee`, `caller_authenticated`.

## Example request

```sh
curl -X POST https://api.tarsana.io/v1/sessions \
  -H "Content-Type: application/json" \
  --data '{"login": "you@example.com", "secret": "YOUR-LOGIN-SECRET"}'
```

## Example response

```json
{
  "session": "YOUR-SESSION",
  "login": "you@example.com",
  "scopes": [
    "operate",
    "read",
    "submit"
  ],
  "tenants": [
    "acme"
  ],
  "expires_at": "2026-10-05T03:15:39Z",
  "guarantee": "namespaces are separated, callers are not authenticated",
  "caller_authenticated": false
}
```

## Errors

| Code | HTTP | What it means |
|---|---|---|
| [`invalid_parameter`](/api/errors#invalid_parameter) | 400 | A value in your request does not have the expected format, for example a submission ID that is not a spec hash. Check the value against the field's description and try again. |
| [`unauthenticated`](/api/errors#unauthenticated) | 401 | Your request has no credential, or one that Tarsana does not recognise. Sign in with `login`, or send a valid access token. |
| [`forbidden`](/api/errors#forbidden) | 403 | Your role does not allow this operation. The response names the roles that do; ask for a credential with one of them. |
| [`rate_limited`](/api/errors#rate_limited) | 429 | You sent too many requests in a short time. Wait for the number of seconds in `retry_after_seconds`, then try again. |
| [`surface_fault`](/api/errors#surface_fault) | 500 | Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening. |