> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create an account, verify email, log in, and send your first message

## Overview

This guide walks you through a minimal, end-to-end flow:

* Set a host and request API credentials.
* Create an account and verify the email address.
* Log in, refresh a token, and log out.
* Send a simple XMPP message.

<Note>
  The Agent API is intended for trusted back-end services that can protect API keys and secrets.
</Note>

## 1. Set up environment variables

Request an API key and secret from the operator at
`https://DOMAIN/RequestApiKey.md`. Replace `DOMAIN` with your Neuron host.

```bash theme={null}
export NEURON_HOST="neuron.example.com"
export NEURON_API_KEY="your-api-key"
export NEURON_API_SECRET="your-api-secret"
export NEURON_USER="alice"
export NEURON_EMAIL="alice@example.com"
export NEURON_PASSWORD="correct-horse-battery-staple"
```

## 2. Create an account

`Account/Create` also logs you in and returns a JWT. The request must be HMAC-signed
with the API secret. See the signing details in
[Authentication](/guides/authentication).

```bash theme={null}
NONCE="random-unique-string-at-least-32-chars"
SIGNATURE="computed-hmac-base64"

curl -sS "https://$NEURON_HOST/Agent/Account/Create" \\
  -H "Content-Type: application/json" \\
  -d '{
    "userName": "'"$NEURON_USER"'",
    "eMail": "'"$NEURON_EMAIL"'",
    "password": "'"$NEURON_PASSWORD"'",
    "apiKey": "'"$NEURON_API_KEY"'",
    "nonce": "'"$NONCE"'",
    "signature": "'"$SIGNATURE"'",
    "seconds": 3600
  }'
```

Example response:

```json theme={null}
{
  "created": "2024-08-02T10:22:11Z",
  "enabled": false,
  "canRelay": true,
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2024-08-02T11:22:11Z"
}
```

## 3. Verify the email address

You will receive a verification code by email. Submit it to enable the account.

```bash theme={null}
curl -sS "https://$NEURON_HOST/Agent/Account/VerifyEMail" \\
  -H "Content-Type: application/json" \\
  -d '{
    "eMail": "'"$NEURON_EMAIL"'",
    "code": "123456"
  }'
```

## 4. Log in to get a JWT

Login uses an HMAC signature based on `userName`, `host`, and a random `nonce`.

```bash theme={null}
NONCE="random-unique-string-at-least-32-chars"
SIGNATURE="computed-hmac-base64"

curl -sS "https://$NEURON_HOST/Agent/Account/Login" \\
  -H "Content-Type: application/json" \\
  -d '{
    "userName": "'"$NEURON_USER"'",
    "nonce": "'"$NONCE"'",
    "signature": "'"$SIGNATURE"'",
    "seconds": 3600
  }'
```

Set `JWT` to the `jwt` value from the response.

## 5. Refresh and log out

```bash theme={null}
curl -sS "https://$NEURON_HOST/Agent/Account/Refresh" \\
  -H "Authorization: Bearer $JWT" \\
  -H "Content-Type: application/json" \\
  -d '{ "seconds": 3600 }'
```

```bash theme={null}
curl -sS "https://$NEURON_HOST/Agent/Account/Logout" \\
  -H "Authorization: Bearer $JWT" \\
  -H "Content-Type: application/json" \\
  -d '{}'
```

## 6. Send a text message

```bash theme={null}
curl -sS "https://$NEURON_HOST/Agent/Xmpp/SendTextMessage" \\
  -H "Authorization: Bearer $JWT" \\
  -H "Content-Type: application/json" \\
  -d '{
    "to": "bob@neuron.example.com",
    "message": "Hello from the Agent API!",
    "language": "en"
  }'
```

## Authentication flow

```mermaid theme={null}
sequenceDiagram
  participant Client
  participant Neuron
  Client->>Neuron: Account/Create (HMAC)
  Neuron-->>Client: JWT + disabled account
  Client->>Neuron: Account/VerifyEMail
  Neuron-->>Client: verified
  Client->>Neuron: Account/Login (HMAC)
  Neuron-->>Client: JWT
  Client->>Neuron: Xmpp/SendTextMessage (JWT)
  Neuron-->>Client: sent
```