Getting started
The Awacino API does from your own tools what an admin does in the Awacino app: create and offboard members, hand out invitation codes, list Beam-in and Beam-out devices, enrol servers, create Beam-in codes for your customers, decide which Beam-in devices each member may use, see who is connected, and read the audit log. The official Terraform provider awacino/awacino is built on it.
1. The API Access package
- API Access is included in Premium. On Basic and Standard it costs €9.99 a month (€99.90 a year), plus VAT. Add it in the app or on the pricing page.
- Access grants per member (
/v1/members/{id}/access, /v1/connections/grants) also need the Management package, included in Standard and Premium.
2. Create a key in the app
- In the Awacino app, open Company → API keys. Only MAIN-ADMIN and ADMIN accounts open it.
- Tap New API key and give it a description, for example "Terraform prod" or "HR sync".
- Sections: tick what the key may use - Users, Connections and Audit, each with Read and / or Write (Audit is read only). Presets: Read only, Full provisioning, Audit only.
- Lifetime: 3, 6, 12 or 24 months, or a date - at most 24 months.
- IP allow-list (optional): the addresses your automation runs from, as CIDRs, for example
203.0.113.0/28.
- Two-step confirmation: creating a key - and ticking a section later - asks you to confirm with an authenticator app or a passkey.
- The app shows the key id (
awk_01JD3Z8V9K2M4N6P8Q0R2S4T6V, public) and the secret (aws_…). The secret is shown once. Store it in your secret manager now; Awacino keeps only a hash and cannot show it again.
The key list shows when each key was created, when it expires, when and from which IP it was last used, who created it and its sections. Edit access changes the sections; unticking applies within 60 seconds. Revoke takes effect within 60 seconds. To rotate a key, create a second one, switch your systems over, then revoke the first. Admins get an e-mail when a key is created or revoked, and 14 and 3 days before it expires.
Sections and scopes
| Section | Read | Write | Covers |
| Users | users:read | users:write | Members, invitations, seats, ending sessions |
| Connections | connections:read | connections:write | Beam-in devices and enrolments, Beam-in codes, access grants, active connections |
| Audit | audit:read | - | The audit API /audit/v1: read and export |
- Write includes read. Any combination is allowed - still, give each system its own key with the fewest sections it needs: a security monitoring system gets a key with Audit only.
- A section that is not ticked answers
403 insufficient_scope; the error names the required_scope. Every operation in the reference names its scope.
GET /v1/key works for every key and shows its sections and expiry.
A key never creates or changes ADMIN or MAIN-ADMIN accounts, never changes security, sign-in, SSO, SCIM or domain settings, and never creates, changes or lists keys. That stays with a person behind a second factor.
3. Your first call
curl https://api.awacino.net/v1/key \
-H "X-Awacino-Key-Id: $AWACINO_KEY_ID" \
-H "X-Awacino-Key-Secret: $AWACINO_KEY_SECRET"
Authentication
Use one of the three forms on each request. Sending two forms answers 400 ambiguous_credentials.
Key headers (recommended)
curl https://api.awacino.net/v1/company \
-H "X-Awacino-Key-Id: $AWACINO_KEY_ID" \
-H "X-Awacino-Key-Secret: $AWACINO_KEY_SECRET"
HTTP Basic
The key id is the user name, the secret is the password - for tools that only speak Basic.
curl -u "$AWACINO_KEY_ID:$AWACINO_KEY_SECRET" https://api.awacino.net/v1/company
OAuth 2.0 client credentials
Exchange the key at POST https://api.awacino.net/v1/oauth/token for a 15-minute bearer token - when your platform expects OAuth, or when you do not want the long-lived secret on every call. scope can only narrow the key's scopes.
TOKEN=$(curl -s https://api.awacino.net/v1/oauth/token \
-d grant_type=client_credentials \
-d client_id="$AWACINO_KEY_ID" \
--data-urlencode client_secret="$AWACINO_KEY_SECRET" \
-d scope="users:read connections:read" | jq -r .access_token)
curl https://api.awacino.net/v1/members -H "Authorization: Bearer $TOKEN"
- The token cannot be refreshed - ask for a new one. It is valid only for this API.
- It stops working within 60 seconds when the key is revoked.
Keeping keys safe
- Keep secrets out of source code, CI logs and tickets; use your CI's secret store or Vault.
- Use the IP allow-list for keys that run from fixed addresses.
- Repeated failed sign-ins from one IP are blocked for 15 minutes.
Base URL and requests
| Base URL | https://api.awacino.net/v1 - provisioning and the token
https://api.awacino.net/audit/v1 - the audit API |
| Format | JSON over HTTPS (TLS 1.2 or newer), UTF-8, times in RFC 3339 UTC |
| Changes | PATCH takes application/merge-patch+json; create, PATCH and PUT return the full object |
| Ids | Every object has a stable id (mem_…, inst_…, enr_…, grt_…, bic_…) - never a code, never an e-mail. Members, enrolments and codes also take your own external_id, unique per company |
| Request id | Every response carries X-Request-Id. Quote it when you write to support@awacino.com |
List endpoints take limit (1-200, default 50) and cursor, and answer {"data": [...], "next_cursor": "..."}. Pass next_cursor as cursor until it is null. Cursors are opaque; the order is stable.
cursor=""
while :; do
page=$(curl -s -u "$AWACINO_KEY_ID:$AWACINO_KEY_SECRET" \
"https://api.awacino.net/v1/members?limit=200${cursor:+&cursor=$cursor}")
echo "$page" | jq -c '.data[]'
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -z "$cursor" ] && break
done
Rate limits
| Class | Limit per key |
Reads under /v1 | 600 a minute |
Writes under /v1 | 120 a minute |
/audit/v1 | 60 a minute |
/v1/oauth/token | 10 a minute |
| All keys of one company together | 1 200 a minute |
Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 rate_limited carries Retry-After in seconds.
Idempotency-Key
Send an Idempotency-Key header (a UUID is best) on writes. It is required on every POST that creates something. Keys are kept for 24 hours per API key.
| You send | You get |
| The same key with the same body | The first answer again, with Idempotent-Replayed: true |
| The same key with a different body | 422 idempotency_key_reused |
| The same key while the first request still runs | 409 idempotency_in_progress |
Invitation codes, setup codes and Beam-in codes are returned once. A replay answers without the code ("code_redacted": true). If you lost the first answer, issue a new code.
Versioning
- The major version is in the path (
/v1). New fields, endpoints and error codes are added without notice: ignore unknown fields and treat unknown code values as generic errors.
- Breaking changes come only as
/v2. /v1 then keeps working for at least 12 months and announces its end with Deprecation and Sunset headers.
Errors
Errors are RFC 9457 problem details (application/problem+json) with a stable code:
{
"type": "https://www.awacino.com/support/docs/api/errors#seats_full",
"title": "All user seats are taken",
"status": 409,
"code": "seats_full",
"detail": "3 of 3 users are taken. Add users on awacino.com.",
"request_id": "5f0c3c1e-8a4b-4d1e-9a51-1f3b2a7c9d10"
}
| Status | Code | Meaning |
|---|
| 400 | validation_failed | A field is missing or wrong; errors[] lists each field. |
| 400 | ambiguous_credentials | More than one form of authentication on the request. |
| 400 | window_too_large | Audit query: to - from is longer than 31 days. |
| 400 | outside_retention | Audit query: from is older than the company's audit retention. |
| 401 | invalid_credentials | Unknown key id or wrong secret. |
| 401 | key_expired | The key's lifetime has ended - create a new key. |
| 401 | key_revoked | An admin revoked the key. |
| 403 | insufficient_scope | The key lacks the section; required_scope names it. |
| 403 | plan | The company's plan or packages do not include this (API Access, Management, Compliance). |
| 403 | ip_not_allowed | The request comes from an address outside the key's IP allow-list. |
| 403 | role_not_allowed | A key cannot give this role (ADMIN, MAIN-ADMIN). |
| 404 | not_found | No such object in this company. |
| 409 | seats_full | All user seats are taken. |
| 409 | beamin_full | All Beam-in devices of the plan are taken. |
| 409 | already_member | The address is already a member of the company. |
| 409 | not_a_target | The device is not a Beam-in device of the company. |
| 409 | code_limit | The device has reached its number of Beam-in codes. |
| 409 | mint_rate_limited | Too many new codes in a short time - try again shortly. |
| 409 | conflict | The request conflicts with the current state, e.g. a second grant for the same member and device. |
| 409 | idempotency_in_progress | The first request with this Idempotency-Key still runs. |
| 422 | idempotency_key_reused | The Idempotency-Key was used with a different body. |
| 422 | reach_not_enforced_yet | A reach or internet value that access_capabilities of GET /v1/company does not list. |
| 422 | role_sees_all_devices | A grant for a member with role user; provision such members as read. |
| 422 | domain_not_verified | The operation needs a verified company domain. |
| 429 | rate_limited | Too many requests - wait Retry-After seconds. |
| 500 | internal | Something went wrong on our side. Retry with the same Idempotency-Key. |
Every call in the audit log
- Every API call is written to your company's audit log as an
api_request event: actor api:<key_id> with the key's description, IP, method, route, status and request id. Identical reads of one key within 60 seconds are collapsed into one entry with a count; every write, every refusal and every audit read is its own entry.
- Writes also produce the normal events, for example "HR sync (API key awk_…) added dieter@company.com".
- Every audit API call is itself an event (
audit_api_export), so you see who read the log and when.
One code, one network
One Beam-in code or access grant = one Beam-in device = its one network. For several networks, create one code or grant per Beam-in device. Each says exactly how far it reaches:
| Setting | Values |
reach | network - the whole network of the device · device - this machine only · ports - only the listed ports on this machine, e.g. [22, 443] |
internet | none (default) - never · choice - the person decides · full - always through the device's internet line |
valid_until / valid_days | Ends by itself at that time. Pause, resume or revoke at any time - a connected device is disconnected at once |
Beam-in codes take reach as an object ({ "kind": "ports", "ports": [22, 443] }), member grants under /v1/members/{id}/access as a value ("reach": "network"). GET /v1/company lists the values the company's devices accept in access_capabilities. Devices that are not granted are invisible to the member and cannot be reached.
Common tasks
A new colleague: member account and invitation link
curl -X POST https://api.awacino.net/v1/members \
-u "$AWACINO_KEY_ID:$AWACINO_KEY_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hr-4711" \
-d '{ "email": "dieter@company.com", "display_name": "Dieter Muster",
"external_id": "4711", "role": "read",
"invitation": { "days": 7, "send_mail": false } }'
The answer carries invitation.code and invitation.join_url once. With send_mail: false you send join_url in your own mail; the code sits in the URL fragment, so it never reaches a web server log. The person pastes the code in the Awacino app ("Sign in with company account → I have an invitation code") and signs in with Apple, Google or Microsoft. Each active member or open invitation takes one user seat (Basic 3, Standard 10, Premium 20, plus users bought on awacino.com).
Give the member the office network behind one Beam-in device
curl -X PUT https://api.awacino.net/v1/members/mem_1234/access \
-u "$AWACINO_KEY_ID:$AWACINO_KEY_SECRET" \
-H "Content-Type: application/json" \
-d '{ "grants": [ { "device_id": "inst_9f2c41", "reach": "network" } ] }'
A Beam-in code for a customer: SSH and HTTPS on one server, 30 days
curl -X POST https://api.awacino.net/v1/connections/beamin-codes \
-u "$AWACINO_KEY_ID:$AWACINO_KEY_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: cust-4711-web01" \
-d '{ "device_id": "inst_9f2c41",
"reach": { "kind": "ports", "ports": [22, 443] },
"internet": "none", "valid_days": 30,
"label": "Customer 4711 - web-01", "external_id": "cust-4711-web01" }'
code and connect_url come once - hand them to your customer. The code belongs to your company and to the first device that redeems it. A code beyond your plan's active codes is created paused (paused_reason: lobby) and starts when the plan has room for it again.
A new server registers itself as a Beam-in device
curl -X POST https://api.awacino.net/v1/enrolments \
-u "$AWACINO_KEY_ID:$AWACINO_KEY_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: web-02" \
-d '{ "label": "web-02.example.com", "hours": 2 }'
The answer has a one-time setup code and ready install lines (install.docker, install.apt, install.cloud_init). The server connects only outbound, so it needs no open inbound port for Awacino.
Offboarding
curl -X DELETE https://api.awacino.net/v1/members/mem_1234 \
-u "$AWACINO_KEY_ID:$AWACINO_KEY_SECRET" \
-H "Idempotency-Key: offboard-4711"
One call ends every session and live connection, hands the member's Beam-in codes to the company, removes their Beam-out devices from the company and frees the seat. The person's private Awacino account is not touched.
Endpoint reference
38 operations on https://api.awacino.net, generated from the OpenAPI 3.1.0 contract (version 1.0.0). Download openapi.yaml for your API client generator, Postman or Insomnia.
Token and key
Token exchange and the calling key.
POST/v1/oauth/token
Exchange key id + secret for a 15-minute bearer token (OAuth 2.0 client credentials) no key headers
RFC 6749 section 4.4. Client authentication by form fields (client_id, client_secret) or by HTTP Basic (client_secret_basic). scope may only narrow the key's scopes. The token is valid only for /v1 and /audit/v1, is checked against the key on every call (a revoked key stops within 60 s) and cannot be refreshed - request a new one.
Request body application/x-www-form-urlencoded
| Field | Type | Description |
|---|
grant_type required | "client_credentials" | |
client_id | string | |
client_secret | string | The key's secret (aws_...). Omit when using HTTP Basic. |
scope | string | Space-separated subset of the key's scopes. |
200 Token issued.400 OAuth error (invalid_request, unsupported_grant_type, invalid_scope).401 OAuth invalid_client (unknown key, wrong secret, expired or revoked key, IP not allowed).429 Too many requests (rate_limited).
GET/v1/key
The calling key and its sections (works for every key)
200 The key. → ApiKeyInfo401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).429 Too many requests (rate_limited).
Company
The company the key belongs to.
GET/v1/company
The company, its plan, seats and the access rules the server accepts
Any key with the Users or Connections section.
200 The company. → Company401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).429 Too many requests (rate_limited).
Members
Member accounts, invitations and offboarding.
GET/v1/members
List members users:read
Scope users:read.
| Parameter | Type | Description |
|---|
limit query | integer | |
cursor query | string | Opaque cursor from next_cursor of the previous page. |
status query | one of invited, active, deactivated, removed | |
role query | one of main_admin, admin, auditor, user, read | |
email query | string (email) | Exact invited address (case-insensitive). |
external_id query | string | |
200 A page of members.400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).429 Too many requests (rate_limited).
POST/v1/members
Create a member account and its invitation users:write
Scope users:write. Takes a user seat (409 seats_full when all are taken). The response carries the invitation code and join_url once; an idempotent replay returns the member with invitation.code_redacted: true - issue a new code if the first answer was lost. Roles: user, read, and auditor (needs the Compliance package). ADMIN cannot be granted by a key. Without a verified company domain the address is a label only; the code is the proof.
| Parameter | Type | Description |
|---|
Idempotency-Key required header | string | Required on creating requests. Same key + same body replays; same key + other body -> 422. |
Request body · MemberCreate application/json
| Field | Type | Description |
|---|
email required | string (email) | |
display_name | string | |
external_id | string | |
role | one of user, read, auditor | Default "read". |
can_automation | boolean | READ only; default false. |
can_agentic | boolean | READ only; default false. |
invitation | InvitationRequest | |
access | array of AccessGrantInput | Optional initial grants (needs Management and connections:write). At most 200 items. |
200 Idempotent replay (Idempotent-Replayed: true). → MemberWithInvitation201 Created. → MemberWithInvitation400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).409 Conflicts with the current state (seats_full, already_member, beamin_full, not_a_target, code_limit, mint_rate_limited, idempotency_in_progress, conflict).422 Valid JSON that cannot be applied (idempotency_key_reused, reach_not_enforced_yet, role_sees_all_devices, domain_not_verified).429 Too many requests (rate_limited).
GET/v1/members/{member_id}
Get a member users:read
Scope users:read.
| Parameter | Type | Description |
|---|
member_id required path | string | |
200 The member. → Member401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
PATCH/v1/members/{member_id}
Edit a member (role, rights, labels, deactivate / reactivate) users:write
Scope users:write. ADMIN and MAIN-ADMIN members cannot be changed by a key (403 role_not_allowed). active: false deactivates: sessions and live connections end, the seat is freed. active: true reactivates (needs a free seat).
| Parameter | Type | Description |
|---|
member_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
Request body · MemberPatch application/merge-patch+json
| Field | Type | Description |
|---|
role | one of user, read, auditor | |
can_automation | boolean | |
can_agentic | boolean | |
display_name | string or null | |
external_id | string or null | |
active | boolean | false = deactivate, true = reactivate. |
200 The updated member. → Member400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).409 Conflicts with the current state (seats_full, already_member, beamin_full, not_a_target, code_limit, mint_rate_limited, idempotency_in_progress, conflict).422 Valid JSON that cannot be applied (idempotency_key_reused, reach_not_enforced_yet, role_sees_all_devices, domain_not_verified).429 Too many requests (rate_limited).
DELETE/v1/members/{member_id}
Offboard (remove) a member users:write
Scope users:write. Ends every session, live connection and member credential at once, moves the member's Beam-in codes to the company, frees the seat and removes the member's Beam-out devices from the company. The member's private Awacino account is not touched.
| Parameter | Type | Description |
|---|
member_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
204 Offboarded.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
GET/v1/members/{member_id}/invitation
Invitation status (never the code) users:read
Scope users:read. Codes are stored as hashes only and cannot be read back.
| Parameter | Type | Description |
|---|
member_id required path | string | |
200 The open invitation. → InvitationStatus401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
POST/v1/members/{member_id}/invitation
Issue a new invitation code (revokes the older one) users:write
Scope users:write. Only for members with status invited. Returns the code and the join link once, for your own mail system (send_mail: false) or mailed by Awacino (send_mail: true).
| Parameter | Type | Description |
|---|
member_id required path | string | |
Idempotency-Key required header | string | Required on creating requests. Same key + same body replays; same key + other body -> 422. |
Request body · InvitationRequest application/json
| Field | Type | Description |
|---|
days | integer | Default 7. 1-14. |
send_mail | boolean | true = Awacino mails the invited address. Default false. |
locale | string | Mail language (ISO 639-1, e.g. de, nb, pt). Default "en". |
201 Issued. → Invitation401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).409 Conflicts with the current state (seats_full, already_member, beamin_full, not_a_target, code_limit, mint_rate_limited, idempotency_in_progress, conflict).429 Too many requests (rate_limited).
DELETE/v1/members/{member_id}/invitation
Revoke the open invitation code users:write
Scope users:write. The member stays invited (with no valid code) until a new code is issued or the member is removed.
| Parameter | Type | Description |
|---|
member_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
204 Revoked.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
POST/v1/members/{member_id}/end-sessions
Sign the member out everywhere users:write
Scope users:write. Ends sessions and live connections; the member stays active and may sign in again.
| Parameter | Type | Description |
|---|
member_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
204 Sessions ended.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
Devices and enrolment
Beam-in and Beam-out devices and server enrolment.
GET/v1/devices
List company devices (Beam-in and Beam-out) connections:read
Scope connections:read.
| Parameter | Type | Description |
|---|
limit query | integer | |
cursor query | string | Opaque cursor from next_cursor of the previous page. |
role query | one of beamin, beamout | |
kind query | one of app, unattended | |
status query | one of active, lobby | |
member_id query | string | Devices registered by this member. |
external_id query | string | The external_id given at enrolment. |
name query | string | Exact device name (case-insensitive). |
200 A page of devices.400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).429 Too many requests (rate_limited).
GET/v1/devices/{device_id}
Get a device connections:read
Scope connections:read.
| Parameter | Type | Description |
|---|
device_id required path | string | |
200 The device. → Device401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
PATCH/v1/devices/{device_id}
Rename a device or change its role connections:write
Scope connections:write. A role change follows the plan (Beam-in devices per tier); a device beyond the limit goes to the Lobby (status: lobby).
| Parameter | Type | Description |
|---|
device_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
Request body application/json
| Field | Type | Description |
|---|
name | string | |
role | one of beamin, beamout | Beam-in = can be reached (a target); Beam-out = connects out into the company's devices. |
200 The device. → Device400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).409 Conflicts with the current state (seats_full, already_member, beamin_full, not_a_target, code_limit, mint_rate_limited, idempotency_in_progress, conflict).429 Too many requests (rate_limited).
DELETE/v1/devices/{device_id}
Remove a device from the company connections:write
Scope connections:write. An app install leaves the company's device list (as the app's Remove); an unattended device is removed (and remembered, so the app can restore it). Revoking its Beam-in codes and ending live connections to it follow with the connection API (/v1/connections/beamin-codes).
| Parameter | Type | Description |
|---|
device_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
204 Removed.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
GET/v1/enrolments
Open enrol codes connections:read
Scope connections:read. Codes themselves are never listed again.
| Parameter | Type | Description |
|---|
limit query | integer | |
cursor query | string | Opaque cursor from next_cursor of the previous page. |
200 A page of enrolments.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).429 Too many requests (rate_limited).
POST/v1/enrolments
One-time enrol code for an unattended server connections:write
Scope connections:write. The server installs the Awacino client with this code and registers as a Beam-in device of the company (subject to the plan's Beam-in limit). The code and the install lines are returned once. The code is the setup code the Docker image reads from AWACINO_SETUP_CODE and the Linux installer carries; it pairs only until expires_at (a revoked or expired one never pairs).
| Parameter | Type | Description |
|---|
Idempotency-Key required header | string | Required on creating requests. Same key + same body replays; same key + other body -> 422. |
Request body application/json
| Field | Type | Description |
|---|
label required | string | |
external_id | string | |
hours | integer | Default 2. 1-24. |
201 Created. → EnrolmentCreated400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).409 Conflicts with the current state (seats_full, already_member, beamin_full, not_a_target, code_limit, mint_rate_limited, idempotency_in_progress, conflict).429 Too many requests (rate_limited).
GET/v1/enrolments/{enrolment_id}
One enrolment and, once the server registered, its device connections:read
Scope connections:read. state moves from open to used (with device_id) when the server has installed the client and registered. Poll with back-off (2 to 30 s); the Terraform provider does this for wait_for_device.
| Parameter | Type | Description |
|---|
enrolment_id required path | string | |
200 The enrolment. → Enrolment401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
DELETE/v1/enrolments/{enrolment_id}
Revoke an unused enrol code connections:write
Scope connections:write.
| Parameter | Type | Description |
|---|
enrolment_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
204 Revoked.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
Member access
Which devices a member may use, and how far (per member; the same grants as /connections/grants).
GET/v1/members/{member_id}/access
The member's device grants connections:read
Scope connections:read; needs Management.
| Parameter | Type | Description |
|---|
member_id required path | string | |
200 Grants.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
POST/v1/members/{member_id}/access
Add one grant connections:write
Scope connections:write; needs Management. Same rules as PUT.
| Parameter | Type | Description |
|---|
member_id required path | string | |
Idempotency-Key required header | string | Required on creating requests. Same key + same body replays; same key + other body -> 422. |
Request body · AccessGrantInput application/json
| Field | Type | Description |
|---|
device_id required | string | |
reach required | one of network, device_network, device, ports | network - the device and its whole network (device_network is the older name, still accepted). device - this machine only. ports - only ports on this machine. One grant = one Beam-in device = its one network. Several networks: one grant per Beam-in device. |
ports | array of integer | At most 32 items. |
internet | one of none, choice, full | Internet routing through the device. |
valid_until | string (date-time) | Grant end. |
201 Added. → AccessGrant400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).409 Conflicts with the current state (seats_full, already_member, beamin_full, not_a_target, code_limit, mint_rate_limited, idempotency_in_progress, conflict).422 Valid JSON that cannot be applied (idempotency_key_reused, reach_not_enforced_yet, role_sees_all_devices, domain_not_verified).429 Too many requests (rate_limited).
PUT/v1/members/{member_id}/access
Replace all grants of the member (declarative) connections:write
Scope connections:write; needs Management. The list becomes the member's complete access; devices not listed are no longer reachable (live connections to them end). A grant naming a value that Company.access_capabilities does not list is refused with 422 reach_not_enforced_yet. Device lists restrict members with role read; a grant for a user member answers 422 role_sees_all_devices - provision such members as read.
| Parameter | Type | Description |
|---|
member_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
Request body application/json
200 The member's grants now.400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).422 Valid JSON that cannot be applied (idempotency_key_reused, reach_not_enforced_yet, role_sees_all_devices, domain_not_verified).429 Too many requests (rate_limited).
DELETE/v1/members/{member_id}/access/{grant_id}
Remove one grant connections:write
Scope connections:write. Live connections covered only by this grant end.
| Parameter | Type | Description |
|---|
member_id required path | string | |
grant_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
204 Removed.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
Connections
The connection API: Beam-in codes for a Beam-in device (create, list, pause, revoke, sessions), members' access grants with an end date, and live connections per device. Section Connections.
GET/v1/connections/beamin-codes
List Beam-in codes of the company connections:read
Scope connections:read. The code itself is never listed; code_hint shows its last 4 characters.
| Parameter | Type | Description |
|---|
limit query | integer | |
cursor query | string | Opaque cursor from next_cursor of the previous page. |
device_id query | string | |
state query | one of active, paused, expired, revoked | |
label query | string | Exact label (case-insensitive). |
external_id query | string | |
200 A page of codes.400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).429 Too many requests (rate_limited).
POST/v1/connections/beamin-codes
Create a Beam-in code for a Beam-in device connections:write
Scope connections:write. The code reaches exactly the reach you choose in one network - the whole network, one device, or ports on the device - with optional internet use and an end date. Several networks: one code per network. The response carries code and connect_url once; an idempotent replay answers with code_redacted: true. The code belongs to the company and is bound to the first device that redeems it. A code beyond the plan's active-code limit is created paused (state: paused, paused_reason: lobby) and becomes active when the plan has room for it again. Plan limits that changed the request are listed in clamped_by_plan.
| Parameter | Type | Description |
|---|
Idempotency-Key required header | string | Required on creating requests. Same key + same body replays; same key + other body -> 422. |
Request body · BeaminCodeCreate application/json
| Field | Type | Description |
|---|
device_id required | string | A Beam-in device of the company. |
reach required | Reach | What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network. |
internet | one of none, choice, full | Use the device's internet: none never, choice the person decides, full always. Default "none". |
expires_at | string (date-time) | End of the code. Give this or valid_days; neither = no end (where the plan allows). |
valid_days | integer | 1-365. |
label | string | |
external_id | string | Your id; unique per company among live codes. |
200 Idempotent replay (Idempotent-Replayed: true); without the code. → BeaminCodeCreated201 Created. → BeaminCodeCreated400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).409 Conflicts with the current state (seats_full, already_member, beamin_full, not_a_target, code_limit, mint_rate_limited, idempotency_in_progress, conflict).422 Valid JSON that cannot be applied (idempotency_key_reused, reach_not_enforced_yet, role_sees_all_devices, domain_not_verified).429 Too many requests (rate_limited).
GET/v1/connections/beamin-codes/{code_id}
Get a Beam-in code (never the code itself) connections:read
Scope connections:read.
| Parameter | Type | Description |
|---|
code_id required path | string | The code's stable id (bic_...), never the code itself. |
200 The code. → BeaminCode401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
PATCH/v1/connections/beamin-codes/{code_id}
Pause or resume a code, change its label, end it earlier connections:write
Scope connections:write. paused: true stops new connections and ends live ones; paused: false resumes (a code the plan paused stays in the Lobby until the plan has room for it again). expires_at can only move earlier. Reach, internet and device cannot change - create a new code and revoke this one.
| Parameter | Type | Description |
|---|
code_id required path | string | The code's stable id (bic_...), never the code itself. |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
Request body · BeaminCodePatch application/merge-patch+json
| Field | Type | Description |
|---|
label | string | |
paused | boolean | |
expires_at | string (date-time) | Only earlier than the current end. |
external_id | string or null | |
200 The code. → BeaminCode400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).409 Conflicts with the current state (seats_full, already_member, beamin_full, not_a_target, code_limit, mint_rate_limited, idempotency_in_progress, conflict).429 Too many requests (rate_limited).
DELETE/v1/connections/beamin-codes/{code_id}
Revoke a Beam-in code connections:write
Scope connections:write. The code stops working everywhere; a device connected with it is disconnected at once. A second call answers 404.
| Parameter | Type | Description |
|---|
code_id required path | string | The code's stable id (bic_...), never the code itself. |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
204 Revoked.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
GET/v1/connections/beamin-codes/{code_id}/sessions
Who used the code, when and for how long connections:read
Scope connections:read. Newest first.
| Parameter | Type | Description |
|---|
code_id required path | string | The code's stable id (bic_...), never the code itself. |
limit query | integer | |
cursor query | string | Opaque cursor from next_cursor of the previous page. |
200 A page of sessions.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
GET/v1/connections/grants
Members' access to Beam-in devices connections:read
Scope connections:read; needs Management. The same grants as /members/{id}/access.
| Parameter | Type | Description |
|---|
limit query | integer | |
cursor query | string | Opaque cursor from next_cursor of the previous page. |
member_id query | string | |
device_id query | string | |
200 A page of grants.400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).429 Too many requests (rate_limited).
POST/v1/connections/grants
Grant a member access to a Beam-in device connections:write
Scope connections:write; needs Management. Same reach options as a Beam-in code, plus an end date (valid_until). One grant per member and device: a second POST for the same pair answers 409 conflict with the existing grant id in detail. A grant accepts what the server enforces for members today, as listed in Company.access_capabilities (reach network and valid_until); device, ports and internet answer 422 reach_not_enforced_yet.
| Parameter | Type | Description |
|---|
Idempotency-Key required header | string | Required on creating requests. Same key + same body replays; same key + other body -> 422. |
Request body · ConnectionGrantCreate application/json
| Field | Type | Description |
|---|
member_id required | string | |
device_id required | string | |
reach required | Reach | What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network. |
internet | one of none, choice, full | Use the device's internet: none never, choice the person decides, full always. Default "none". |
valid_until | string or null (date-time) | The grant ends at this instant. |
201 Created. → ConnectionGrant400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).409 Conflicts with the current state (seats_full, already_member, beamin_full, not_a_target, code_limit, mint_rate_limited, idempotency_in_progress, conflict).422 Valid JSON that cannot be applied (idempotency_key_reused, reach_not_enforced_yet, role_sees_all_devices, domain_not_verified).429 Too many requests (rate_limited).
GET/v1/connections/grants/{grant_id}
Get a grant connections:read
Scope connections:read; needs Management.
| Parameter | Type | Description |
|---|
grant_id required path | string | |
200 The grant. → ConnectionGrant401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
PATCH/v1/connections/grants/{grant_id}
Change reach, internet or end date of a grant connections:write
Scope connections:write; needs Management. A narrower reach ends live connections that fall outside it.
| Parameter | Type | Description |
|---|
grant_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
Request body · ConnectionGrantPatch application/merge-patch+json
| Field | Type | Description |
|---|
reach | Reach | What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network. |
internet | one of none, choice, full | Use the device's internet: none never, choice the person decides, full always. Default "none". |
valid_until | string or null (date-time) | |
200 The grant. → ConnectionGrant400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).422 Valid JSON that cannot be applied (idempotency_key_reused, reach_not_enforced_yet, role_sees_all_devices, domain_not_verified).429 Too many requests (rate_limited).
DELETE/v1/connections/grants/{grant_id}
Revoke a grant connections:write
Scope connections:write; needs Management. The member loses the device; live connections covered only by this grant end within 5 seconds.
| Parameter | Type | Description |
|---|
grant_id required path | string | |
Idempotency-Key header | string | Unique per logical operation (UUID recommended). Kept 24 hours per key. |
204 Revoked.401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).404 Not found in this company (not_found).429 Too many requests (rate_limited).
GET/v1/connections/active
Live connections per Beam-in device connections:read
Scope connections:read. Who is connected to which Beam-in device right now, since when and how (via: a member, the owner's own device, or a Beam-in code). Members are shown by id; code holders by the code's label and the name their device reported - never another account's e-mail.
| Parameter | Type | Description |
|---|
limit query | integer | |
cursor query | string | Opaque cursor from next_cursor of the previous page. |
device_id query | string | |
member_id query | string | |
via query | one of member, own_device, beamin_code | |
200 A page of live connections.400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).429 Too many requests (rate_limited).
Audit
Audit events (section Audit, scope audit:read).
POST/audit/v1/events
Audit events for a time window audit:read
Scope audit:read (section Audit); needs API Access. to - from at most 31 days per call; from not older than the company's audit retention (Basic 30, Standard 90, Premium 180, Compliance 365 days). Ordered by chain_seq; each event carries the hash chain fields so a receiver can verify it. Every call is itself an audit event (audit_api_export).
Request body · AuditQuery application/json
| Field | Type | Description |
|---|
from required | string (date-time) | |
to required | string (date-time) | Exclusive; to - from <= 31 days. |
filter | object | |
filter.actor | string | Actor label, e-mail or api:<key_id>. |
filter.action | array of string | At most 50 items. |
filter.device | string | Device id. |
filter.member_id | string | |
limit | integer | Default 500. 1-1000. |
cursor | string or null | |
format | one of json, ndjson, csv | Default "json". |
200 A page of events. format: json -> AuditPage; ndjson -> one AuditEvent per line; csv -> RFC 4180 with a header row. For ndjson and csv the next cursor is in X-Next-Cursor (absent on the last page). → AuditPage400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).429 Too many requests (rate_limited).
GET/audit/v1/verify
Verify the audit hash chain for a window audit:read
Scope audit:read. Same window rules as /events.
| Parameter | Type | Description |
|---|
from required query | string (date-time) | |
to required query | string (date-time) | |
200 Result.400 The request is malformed (validation_failed, window_too_large, outside_retention, ambiguous_credentials).401 Missing or invalid credentials (invalid_credentials, key_expired, key_revoked).403 Authenticated, not allowed (insufficient_scope with required_scope, plan, ip_not_allowed, role_not_allowed).429 Too many requests (rate_limited).
The official provider awacino/awacino is in the Terraform Registry and works with Terraform and OpenTofu. It is built only on this API.
terraform {
required_providers {
awacino = { source = "awacino/awacino", version = "~> 1.0" }
}
}
provider "awacino" {
key_id = var.awacino_key_id # or AWACINO_KEY_ID
key_secret = var.awacino_key_secret # or AWACINO_KEY_SECRET (sensitive)
# endpoint = "https://api.awacino.net" (the default; AWACINO_ENDPOINT overrides)
}
The key needs the sections Users and Connections, read and write. The provider exchanges it for a token and renews the token by itself; when a section is missing, it says so when it starts.
| Resource | What it manages |
awacino_member | A member account and its first invitation (send_invitation); destroy = offboard. Import by id or external_id:<x> |
awacino_invitation | A new invitation code for an invited member; destroy = revoke |
awacino_beamin_device | A server's one-time setup code with install lines and cloud_init; with wait_for_device it waits until the server registered and exports device_id |
awacino_access_grant | A member's access to one Beam-in device: reach, internet, valid_until |
awacino_beamin_code | A Beam-in code for one Beam-in device: reach, internet, valid_days / expires_at, label, paused. Changing reach, internet or device makes a new code and revokes the old one |
Data sources: awacino_company, awacino_members, awacino_member, awacino_devices, awacino_device, awacino_active_connections and awacino_api_key (the calling key - keys themselves are created by an admin in the app). Every resource supports terraform import. Codes and setup codes are sensitive values: keep your state in an encrypted backend, or use the write-only attributes (Terraform 1.11 and later) so they never reach the state.
A hoster: a new server and a Beam-in code for its customer
# 1. a one-time setup code for the new server, with a ready cloud-init document
resource "awacino_beamin_device" "web01" {
label = "web-01.cust4711.example.net"
external_id = "cust4711-web01"
hours = 2
wait_for_device = true # wait until the server has registered
wait_timeout = "15m"
}
# 2. the server itself, with your cloud provider; the setup code travels in user_data
resource "hcloud_server" "web01" {
name = "web-01"
server_type = "cx22"
image = "debian-12"
user_data = awacino_beamin_device.web01.cloud_init
}
# 3. the customer's Beam-in code: only SSH and HTTPS on this server, 30 days
resource "awacino_beamin_code" "web01_customer" {
device_id = awacino_beamin_device.web01.device_id
label = "Customer 4711 - web-01"
external_id = "cust4711-web01-code"
reach = { kind = "ports", ports = [22, 443] }
internet = "none"
valid_days = 30
}
output "customer_connect_url" {
value = awacino_beamin_code.web01_customer.connect_url
sensitive = true
}
An IT partner: a technician with access to two customer devices
data "awacino_device" "nas" { name = "Customer 12 - NAS" }
data "awacino_device" "server" { name = "Customer 12 - Server" }
resource "awacino_member" "tech_anna" {
email = "anna@it-partner.example"
display_name = "Anna Berger"
external_id = "tech-017"
role = "read"
send_invitation = { days = 7, locale = "de" }
}
resource "awacino_access_grant" "anna" {
for_each = { nas = data.awacino_device.nas.id, server = data.awacino_device.server.id }
member_id = awacino_member.tech_anna.id
device_id = each.value
reach = { kind = "network" }
internet = "none"
valid_until = "2027-06-30T00:00:00Z" # contract end
}
Without Terraform, cloud-init takes the install.cloud_init document of POST /v1/enrolments as user data, and Ansible or a CI script use the same calls as above.
Audit API and webhook
Use a key with the Audit section (scope audit:read). POST /audit/v1/events returns the company's audit events for a time window:
curl -X POST https://api.awacino.net/audit/v1/events \
-H "X-Awacino-Key-Id: $AUDIT_KEY_ID" \
-H "X-Awacino-Key-Secret: $AUDIT_KEY_SECRET" \
-H "Content-Type: application/json" \
-d '{ "from": "2026-11-01T00:00:00Z", "to": "2026-11-15T00:00:00Z",
"filter": { "action": ["company_member_added", "connect"] },
"limit": 500, "format": "json" }'
| Window per call | to - from at most 31 days (window_too_large) |
| How far back | The company's audit retention: Basic 30, Standard 90, Premium 180 days, with Compliance 365 days (outside_retention) |
| Filters | actor (label, e-mail or api:<key_id>), action[], device, member_id |
| Formats | json (default), ndjson (one event per line), csv |
| Paging | next_cursor in the body for json, in the X-Next-Cursor header for ndjson and csv |
| Integrity | Each event has chain_seq, prev_hash and row_hash; GET /audit/v1/verify?from=&to= checks the hash chain |
Webhook
Instead of pulling, let Awacino push: an admin sets one HTTPS address for the company's audit log in the app. Every five minutes, new entries are posted to it, up to 500 per request, ordered by chain_seq:
POST https://siem.example.com/awacino
Content-Type: application/json
X-Awacino-Signature: t=1763290800,v1=5d41402abc4b2a76b9719d911017c592…
{ "company": "…", "events": [ { "id": "…", "chain_seq": 1042, "action": "connect", … } ] }
Where to set it in the app: User (desktop and web: the account icon top right; phone: User in the sidebar) → Manage company settings → tab Audit log → card Audit log API → section Webhook. Enter the address in Webhook URL and press Save webhook; Remove webhook switches it off.
- Signing secret: shown once, right after saving - copy it then. Saving again creates a new secret and the old one stops working.
- Status: the card shows the last delivery (date and HTTP status) and the number of failures in a row.
- Who: the main admin, or an admin after the second-factor confirmation.
- Plan: available with the API Access package (included in Premium).
- Signature: every delivery is signed with HMAC-SHA256 in the header
X-Awacino-Signature; v1 is the hex HMAC-SHA256 of t + "." + body with the webhook's secret. Check the signature and that t is recent, and use the raw body as received.
- Answer with a
2xx status: the next request starts after the last delivered entry. Any other answer is retried; after 50 failures in a row the webhook switches off and the admin sees it in the app.
- The address must be public HTTPS; redirects are not followed.
// Node.js: check X-Awacino-Signature
const crypto = require("crypto");
function verify(rawBody, header, secret, maxAgeSeconds = 600) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const mac = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= maxAgeSeconds;
return fresh && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}
Objects
The objects the reference links to, as defined in the contract.
Scope
one of users:read, users:write, connections:read, connections:write, audit:read
One checkbox of a key's section. Users = members and invitations; Connections = Beam-in devices, enrolments, Beam-in codes, access grants, active connections; Audit = audit log read and export. A :write scope always comes with its :read. Any combination of sections is allowed.
NextCursor
string or null
Pass as cursor for the next page; null on the last page.
Problem
RFC 9457 problem details.
| Field | Type | Description |
|---|
type required | string (uri) | |
title required | string | |
status required | integer | |
code required | one of invalid_credentials, key_expired, key_revoked, ip_not_allowed, ambiguous_credentials, insufficient_scope, plan, not_a_target, code_limit, mint_rate_limited, role_not_allowed, not_found, validation_failed, conflict, seats_full, beamin_full, already_member, domain_not_verified, reach_not_enforced_yet, role_sees_all_devices, idempotency_key_reused, idempotency_in_progress, window_too_large, outside_retention, rate_limited, internal | Stable machine code. New codes may be added. |
detail | string | |
request_id required | string (uuid) | |
required_scope | one of users:read, users:write, connections:read, connections:write, audit:read | With insufficient_scope - the section the key is missing. |
errors | array of object | Field errors for validation_failed. |
ApiKeyInfo
| Field | Type | Description |
|---|
key_id required | string | |
description required | string | |
scopes required | array of one of users:read, users:write, connections:read, connections:write, audit:read | |
sections | object | The same scopes as the checkboxes of the Awacino API page. |
sections.users | one of none, read, write | |
sections.connections | one of none, read, write | |
sections.audit | one of none, read | |
created_at required | string (date-time) | |
expires_at required | string (date-time) | |
ip_allow | array of string | |
company_id required | string | |
Company
| Field | Type | Description |
|---|
id required | string | |
name required | string | |
plan required | one of company_basic, company_standard, company_premium | |
packages required | array of one of management, security, identity, compliance, branding, api_access | |
seats required | object | |
seats.used | integer | Active members + open invitations. |
seats.total | integer | |
beamin_devices required | object | |
beamin_devices.used | integer | |
beamin_devices.total | integer | |
audit_retention_days | one of 30, 90, 180, 365 | |
access_capabilities required | array of one of network, device_network, device, ports, internet, valid_until | Reach / internet values the server enforces and therefore accepts in grants. Clients read this instead of assuming. |
MemberRole
one of main_admin, admin, auditor, user, read
Keys may assign user, read and auditor (Compliance). main_admin / admin are read-only here.
MemberStatus
one of invited, active, deactivated, removed
Member
| Field | Type | Description |
|---|
id required | string | |
email required | string (email) | The invited address (the member account's address). |
display_name | string or null | |
external_id | string or null | Your id; unique per company. |
role required | one of main_admin, admin, auditor, user, read | Keys may assign user, read and auditor (Compliance). main_admin / admin are read-only here. |
status required | one of invited, active, deactivated, removed | |
can_automation | boolean | |
can_agentic | boolean | |
created_at required | string (date-time) | |
accepted_at | string or null (date-time) | |
deactivated_at | string or null (date-time) | |
created_by | object | Who created the member. |
created_by.kind | one of user, api_key, scim, partner | |
created_by.id | string | |
created_by.label | string | |
signed_in_with | object or null | The identity that redeemed the invitation. |
signed_in_with.provider | one of apple, google, microsoft, sso | |
signed_in_with.email_domain | string | |
MemberCreate
| Field | Type | Description |
|---|
email required | string (email) | |
display_name | string | |
external_id | string | |
role | one of user, read, auditor | Default "read". |
can_automation | boolean | READ only; default false. |
can_agentic | boolean | READ only; default false. |
invitation | InvitationRequest | |
access | array of AccessGrantInput | Optional initial grants (needs Management and connections:write). At most 200 items. |
MemberPatch
| Field | Type | Description |
|---|
role | one of user, read, auditor | |
can_automation | boolean | |
can_agentic | boolean | |
display_name | string or null | |
external_id | string or null | |
active | boolean | false = deactivate, true = reactivate. |
InvitationRequest
| Field | Type | Description |
|---|
days | integer | Default 7. 1-14. |
send_mail | boolean | true = Awacino mails the invited address. Default false. |
locale | string | Mail language (ISO 639-1, e.g. de, nb, pt). Default "en". |
Invitation
| Field | Type | Description |
|---|
code | string | Single-use invitation code. Present only in the first answer. |
join_url | string (uri) | https://www.awacino.com/join/#<code> - the code is in the fragment and never reaches a server log. |
expires_at required | string (date-time) | |
mailed | boolean | |
code_redacted | boolean | true on an idempotent replay - the code is not stored and cannot be returned again. |
InvitationStatus
| Field | Type | Description |
|---|
state required | one of open, used, expired, revoked, none | |
expires_at | string or null (date-time) | |
used_at | string or null (date-time) | |
MemberWithInvitation
| Field | Type | Description |
|---|
id required | string | |
email required | string (email) | The invited address (the member account's address). |
display_name | string or null | |
external_id | string or null | Your id; unique per company. |
role required | one of main_admin, admin, auditor, user, read | Keys may assign user, read and auditor (Compliance). main_admin / admin are read-only here. |
status required | one of invited, active, deactivated, removed | |
can_automation | boolean | |
can_agentic | boolean | |
created_at required | string (date-time) | |
accepted_at | string or null (date-time) | |
deactivated_at | string or null (date-time) | |
created_by | object | Who created the member. |
created_by.kind | one of user, api_key, scim, partner | |
created_by.id | string | |
created_by.label | string | |
signed_in_with | object or null | The identity that redeemed the invitation. |
signed_in_with.provider | one of apple, google, microsoft, sso | |
signed_in_with.email_domain | string | |
invitation | Invitation | |
DeviceRole
one of beamin, beamout
Beam-in = can be reached (a target); Beam-out = connects out into the company's devices.
Device
| Field | Type | Description |
|---|
id required | string | |
name required | string | |
role required | one of beamin, beamout | Beam-in = can be reached (a target); Beam-out = connects out into the company's devices. |
kind required | one of app, unattended | |
status required | one of active, lobby | |
platform required | string | |
member_id | string or null | The member who registered it. |
external_id | string or null | |
first_seen | string (date-time) | |
last_seen | string or null (date-time) | Beam-in devices only; Beam-out devices are passive. |
Enrolment
| Field | Type | Description |
|---|
id required | string | |
label required | string | |
external_id | string or null | |
expires_at required | string (date-time) | |
state required | one of open, used, expired, revoked | |
device_id | string or null | |
EnrolmentCreated
| Field | Type | Description |
|---|
id required | string | |
label required | string | |
external_id | string or null | |
expires_at required | string (date-time) | |
state required | one of open, used, expired, revoked | |
device_id | string or null | |
code required | string | One-time enrol code. Returned once. |
install required | object | |
install.docker | string | A docker run line. |
install.apt | string | Shell lines for Debian / Ubuntu. |
install.cloud_init | string | A #cloud-config document. |
AccessGrant
| Field | Type | Description |
|---|
device_id required | string | |
reach required | one of network, device_network, device, ports | network - the device and its whole network (device_network is the older name, still accepted). device - this machine only. ports - only ports on this machine. One grant = one Beam-in device = its one network. Several networks: one grant per Beam-in device. |
ports | array of integer | At most 32 items. |
internet | one of none, choice, full | Internet routing through the device. |
valid_until | string (date-time) | Grant end. |
id required | string | |
created_at required | string (date-time) | |
created_by | object | |
created_by.kind | one of user, api_key, partner | |
created_by.id | string | |
AuditQuery
| Field | Type | Description |
|---|
from required | string (date-time) | |
to required | string (date-time) | Exclusive; to - from <= 31 days. |
filter | object | |
filter.actor | string | Actor label, e-mail or api:<key_id>. |
filter.action | array of string | At most 50 items. |
filter.device | string | Device id. |
filter.member_id | string | |
limit | integer | Default 500. 1-1000. |
cursor | string or null | |
format | one of json, ndjson, csv | Default "json". |
AuditEvent
| Field | Type | Description |
|---|
id required | string | |
chain_seq required | integer | |
created_at required | string (date-time) | |
action required | string | |
actor | string or null | |
actor_ip | string or null | |
target | string or null | |
target_ip | string or null | |
device_id | string or null | |
ended_at | string or null (date-time) | |
duration_seconds | integer or null | |
details | object or null | |
prev_hash | string or null | |
row_hash required | string | |
AuditPage
| Field | Type | Description |
|---|
data required | array of AuditEvent | |
next_cursor required | string or null | Pass as cursor for the next page; null on the last page. |
Reach
What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network.
| Field | Type | Description |
|---|
kind required | one of network, device, ports | |
ports | array of integer | Required for ports. At most 16 items. |
Internet
one of none, choice, full
Use the device's internet: none never, choice the person decides, full always.
CreatedBy
| Field | Type | Description |
|---|
kind | one of user, api_key, scim, partner | |
id | string | |
label | string | |
BeaminCodeState
one of active, paused, expired, revoked
BeaminCodeCreate
| Field | Type | Description |
|---|
device_id required | string | A Beam-in device of the company. |
reach required | Reach | What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network. |
internet | one of none, choice, full | Use the device's internet: none never, choice the person decides, full always. Default "none". |
expires_at | string (date-time) | End of the code. Give this or valid_days; neither = no end (where the plan allows). |
valid_days | integer | 1-365. |
label | string | |
external_id | string | Your id; unique per company among live codes. |
BeaminCode
| Field | Type | Description |
|---|
id required | string | Stable id. Never the code. |
device_id required | string | |
device_name | string | |
label | string | |
external_id | string or null | |
reach required | Reach | What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network. |
internet required | one of none, choice, full | Use the device's internet: none never, choice the person decides, full always. Default "none". |
state required | one of active, paused, expired, revoked | |
paused_reason | one of admin, lobby, null | |
code_hint | string | Last 4 characters of the code. |
expires_at | string or null (date-time) | |
bound_device | object or null | The device that redeemed the code first; only it can use the code. |
bound_device.label | string | |
bound_device.platform | one of ios, android, macos, windows, linux, web, | |
bound_device.bound_at | string (date-time) | |
uses | integer | |
last_used_at | string or null (date-time) | |
created_at required | string (date-time) | |
revoked_at | string or null (date-time) | |
created_by | CreatedBy | |
clamped_by_plan | array of string | What the plan changed in the request, for example expires_at or internet. |
BeaminCodeCreated
| Field | Type | Description |
|---|
id required | string | Stable id. Never the code. |
device_id required | string | |
device_name | string | |
label | string | |
external_id | string or null | |
reach required | Reach | What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network. |
internet required | one of none, choice, full | Use the device's internet: none never, choice the person decides, full always. Default "none". |
state required | one of active, paused, expired, revoked | |
paused_reason | one of admin, lobby, null | |
code_hint | string | Last 4 characters of the code. |
expires_at | string or null (date-time) | |
bound_device | object or null | The device that redeemed the code first; only it can use the code. |
bound_device.label | string | |
bound_device.platform | one of ios, android, macos, windows, linux, web, | |
bound_device.bound_at | string (date-time) | |
uses | integer | |
last_used_at | string or null (date-time) | |
created_at required | string (date-time) | |
revoked_at | string or null (date-time) | |
created_by | CreatedBy | |
clamped_by_plan | array of string | What the plan changed in the request, for example expires_at or internet. |
code | string | The Beam-in code. Present only in the first answer. |
connect_url | string (uri) | https://www.awacino.com/beamin/#<code> - opens the Awacino app with the code; the code is in the fragment and never reaches a server log. |
code_redacted | boolean | true on an idempotent replay - create a new code if the first answer was lost. |
BeaminCodePatch
| Field | Type | Description |
|---|
label | string | |
paused | boolean | |
expires_at | string (date-time) | Only earlier than the current end. |
external_id | string or null | |
CodeSession
| Field | Type | Description |
|---|
id required | string | |
peer_label | string | Name the connecting device reported. |
peer_platform | one of ios, android, macos, windows, linux, web, | |
port | integer or null | |
connected_at required | string (date-time) | |
disconnected_at | string or null (date-time) | |
duration_seconds | integer or null | |
ConnectionGrantCreate
| Field | Type | Description |
|---|
member_id required | string | |
device_id required | string | |
reach required | Reach | What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network. |
internet | one of none, choice, full | Use the device's internet: none never, choice the person decides, full always. Default "none". |
valid_until | string or null (date-time) | The grant ends at this instant. |
ConnectionGrantPatch
| Field | Type | Description |
|---|
reach | Reach | What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network. |
internet | one of none, choice, full | Use the device's internet: none never, choice the person decides, full always. Default "none". |
valid_until | string or null (date-time) | |
ConnectionGrant
| Field | Type | Description |
|---|
member_id required | string | |
device_id required | string | |
reach required | Reach | What a Beam-in code reaches on the Beam-in device's side, always in one network. network - the whole network of the device; device - this machine only; ports - only ports on this machine. Several networks: one code per network. |
internet | one of none, choice, full | Use the device's internet: none never, choice the person decides, full always. Default "none". |
valid_until | string or null (date-time) | The grant ends at this instant. |
id required | string | |
state required | one of active, expired | |
created_at required | string (date-time) | |
created_by | CreatedBy | |
ActiveConnection
| Field | Type | Description |
|---|
id required | string | |
device_id required | string | The Beam-in device that is reached. |
device_name | string | |
via required | one of member, own_device, beamin_code | |
member_id | string or null | |
code_id | string or null | |
code_label | string or null | |
peer_name | string | Name of the connecting device. |
peer_platform | one of ios, android, macos, windows, linux, web, | |
since required | string (date-time) | |
Download and support