API reference

Authentication

Every other request carries the token from POST /api/auth/sign_in in an Authorization: Bearer header. These routes answer plain JSON (application/json), not JSON:API.

Endpoints

post/api/auth/sign_inSign in
post/api/auth/sign_outSign out
get/api/meGet the signed-in user

Sign in

post/api/auth/sign_in

Exchanges an email and password for a session token, valid for 14 days. Sign in once and reuse the token; don't sign in for every request.

Who: Resellers and Customers
Roles: Any active user

A wrong password, an unknown email, an invited or disabled user and a suspended organization all answer the same 401 invalid_credentials.
Limited to 10 requests a minute per IP address, and 5 per 15 minutes per email. Over the limit: 429 rate_limited with a Retry-After header in seconds.

Body

emailstringRequired
passwordstringRequired

Request

curl -X POST https://api.houndsat.com/api/auth/sign_in \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"correct-horse-battery"}'

Response200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "user": {
    "email": "[email protected]",
    "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
    "invite_status": "active",
    "name": "Northwind Freight",
    "organization_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
    "organization_level": "platform",
    "role": "owner"
  }
}

Sign out

post/api/auth/sign_out

Revokes the token used for this request. Reusing it afterwards answers 401.

Who: Resellers and Customers
Roles: Any signed-in user

Request

curl -X POST https://api.houndsat.com/api/auth/sign_out \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"

Response204 No Content

(empty body)

Get the signed-in user

get/api/me

The user behind the token, their organization, its branding and a set of permission flags (what this user may do). Useful to check a token and to learn your organization's id.

Who: Resellers and Customers
Roles: Any signed-in user

Request

curl https://api.houndsat.com/api/me \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"

Response200 OK

{
  "branding": {
    "company_name": "Acme Connect",
    "logo_url": "https://acme.example/logo.png",
    "primary_color": "#3B47E0",
    "support_email": "[email protected]",
    "white_label": false
  },
  "organization": {
    "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
    "level": "platform",
    "name": "Northwind Freight",
    "parent_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
    "status": "active"
  },
  "permissions": {
    "audit_log.read": false,
    "billing.read": false,
    "devices.assign": false,
    "devices.import": false,
    "devices.manage": false,
    "invoices.manage": false,
    "messages.retry": false,
    "organizations.create_child": false,
    "organizations.delete": false,
    "organizations.update": false,
    "organizations.update_branding": false,
    "payment_methods.manage": false,
    "plans.manage": false,
    "usage.import_cdr": false,
    "usage.reconciliation.read": false,
    "users.invite": false,
    "users.manage": false,
    "webhooks.manage": false
  },
  "settings": {
    "reconciliation_tolerance": 1
  },
  "user": {
    "email": "[email protected]",
    "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
    "invite_status": "active",
    "name": "Northwind Freight",
    "organization_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
    "organization_level": "platform",
    "role": "owner"
  }
}