Skip to main content

​
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

Create also logs the user 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

Login uses an HMAC signature based on userName, host, and a random nonce. 
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"
  }'

​
Authentication flow