Quickstart - Neuron Agent API

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.

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

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.

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.

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:

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

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

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

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

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

6. Send a text message

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"
  }'

​Overview

​1. Set up environment variables

​2. Create an account

​3. Verify the email address

​4. Log in to get a JWT

​5. Refresh and log out

​6. Send a text message

​Authentication flow

Overview

1. Set up environment variables

2. Create an account

3. Verify the email address

4. Log in to get a JWT

5. Refresh and log out

6. Send a text message

Authentication flow