Documentation · English

Awacino API

Members, Beam-in devices, Beam-in codes, access and the audit log - from your own tools, on api.awacino.net.

On this page
  1. Getting started
  2. Authentication
  3. Base URL and requests
  4. Errors
  5. Every call in the audit log
  6. One code, one network
  7. Common tasks
  8. Endpoint reference
  9. Terraform
  10. Audit API and webhook
  11. Objects
  12. Download and support

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

  1. In the Awacino app, open Company → API keys. Only MAIN-ADMIN and ADMIN accounts open it.
  2. Tap New API key and give it a description, for example "Terraform prod" or "HR sync".
  3. 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.
  4. Lifetime: 3, 6, 12 or 24 months, or a date - at most 24 months.
  5. IP allow-list (optional): the addresses your automation runs from, as CIDRs, for example 203.0.113.0/28.
  6. Two-step confirmation: creating a key - and ticking a section later - asks you to confirm with an authenticator app or a passkey.
  7. 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

SectionReadWriteCovers
Usersusers:readusers:writeMembers, invitations, seats, ending sessions
Connectionsconnections:readconnections:writeBeam-in devices and enrolments, Beam-in codes, access grants, active connections
Auditaudit: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 URLhttps://api.awacino.net/v1 - provisioning and the token
https://api.awacino.net/audit/v1 - the audit API
FormatJSON over HTTPS (TLS 1.2 or newer), UTF-8, times in RFC 3339 UTC
ChangesPATCH takes application/merge-patch+json; create, PATCH and PUT return the full object
IdsEvery 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 idEvery response carries X-Request-Id. Quote it when you write to support@awacino.com

Pagination

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

ClassLimit per key
Reads under /v1600 a minute
Writes under /v1120 a minute
/audit/v160 a minute
/v1/oauth/token10 a minute
All keys of one company together1 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 sendYou get
The same key with the same bodyThe first answer again, with Idempotent-Replayed: true
The same key with a different body422 idempotency_key_reused
The same key while the first request still runs409 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"
}
StatusCodeMeaning
400validation_failedA field is missing or wrong; errors[] lists each field.
400ambiguous_credentialsMore than one form of authentication on the request.
400window_too_largeAudit query: to - from is longer than 31 days.
400outside_retentionAudit query: from is older than the company's audit retention.
401invalid_credentialsUnknown key id or wrong secret.
401key_expiredThe key's lifetime has ended - create a new key.
401key_revokedAn admin revoked the key.
403insufficient_scopeThe key lacks the section; required_scope names it.
403planThe company's plan or packages do not include this (API Access, Management, Compliance).
403ip_not_allowedThe request comes from an address outside the key's IP allow-list.
403role_not_allowedA key cannot give this role (ADMIN, MAIN-ADMIN).
404not_foundNo such object in this company.
409seats_fullAll user seats are taken.
409beamin_fullAll Beam-in devices of the plan are taken.
409already_memberThe address is already a member of the company.
409not_a_targetThe device is not a Beam-in device of the company.
409code_limitThe device has reached its number of Beam-in codes.
409mint_rate_limitedToo many new codes in a short time - try again shortly.
409conflictThe request conflicts with the current state, e.g. a second grant for the same member and device.
409idempotency_in_progressThe first request with this Idempotency-Key still runs.
422idempotency_key_reusedThe Idempotency-Key was used with a different body.
422reach_not_enforced_yetA reach or internet value that access_capabilities of GET /v1/company does not list.
422role_sees_all_devicesA grant for a member with role user; provision such members as read.
422domain_not_verifiedThe operation needs a verified company domain.
429rate_limitedToo many requests - wait Retry-After seconds.
500internalSomething 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:

SettingValues
reachnetwork - the whole network of the device · device - this machine only · ports - only the listed ports on this machine, e.g. [22, 443]
internetnone (default) - never · choice - the person decides · full - always through the device's internet line
valid_until / valid_daysEnds 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
FieldTypeDescription
grant_type required"client_credentials"
client_idstring
client_secretstringThe key's secret (aws_...). Omit when using HTTP Basic.
scopestringSpace-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. → ApiKeyInfo
  • 401 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. → Company
  • 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).

Members

Member accounts, invitations and offboarding.

GET/v1/members

List members users:read

Scope users:read.

ParameterTypeDescription
limit queryinteger
cursor querystringOpaque cursor from next_cursor of the previous page.
status queryone of invited, active, deactivated, removed
role queryone of main_admin, admin, auditor, user, read
email querystring (email)Exact invited address (case-insensitive).
external_id querystring
  • 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.

ParameterTypeDescription
Idempotency-Key required headerstringRequired on creating requests. Same key + same body replays; same key + other body -> 422.
Request body · MemberCreate application/json
FieldTypeDescription
email requiredstring (email)
display_namestring
external_idstring
roleone of user, read, auditorDefault "read".
can_automationbooleanREAD only; default false.
can_agenticbooleanREAD only; default false.
invitationInvitationRequest
accessarray of AccessGrantInputOptional initial grants (needs Management and connections:write). At most 200 items.
  • 200 Idempotent replay (Idempotent-Replayed: true). → MemberWithInvitation
  • 201 Created. → MemberWithInvitation
  • 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).
  • 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.

ParameterTypeDescription
member_id required pathstring
  • 200 The member. → Member
  • 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).

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).

ParameterTypeDescription
member_id required pathstring
Idempotency-Key headerstringUnique per logical operation (UUID recommended). Kept 24 hours per key.
Request body · MemberPatch application/merge-patch+json
FieldTypeDescription
roleone of user, read, auditor
can_automationboolean
can_agenticboolean
display_namestring or null
external_idstring or null
activebooleanfalse = deactivate, true = reactivate.
  • 200 The updated member. → Member
  • 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).
  • 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.

ParameterTypeDescription
member_id required pathstring
Idempotency-Key headerstringUnique 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.

ParameterTypeDescription
member_id required pathstring
  • 200 The open invitation. → InvitationStatus
  • 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}/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).

ParameterTypeDescription
member_id required pathstring
Idempotency-Key required headerstringRequired on creating requests. Same key + same body replays; same key + other body -> 422.
Request body · InvitationRequest application/json
FieldTypeDescription
daysintegerDefault 7. 1-14.
send_mailbooleantrue = Awacino mails the invited address. Default false.
localestringMail language (ISO 639-1, e.g. de, nb, pt). Default "en".
  • 201 Issued. → Invitation
  • 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/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.

ParameterTypeDescription
member_id required pathstring
Idempotency-Key headerstringUnique 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.

ParameterTypeDescription
member_id required pathstring
Idempotency-Key headerstringUnique 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.

ParameterTypeDescription
limit queryinteger
cursor querystringOpaque cursor from next_cursor of the previous page.
role queryone of beamin, beamout
kind queryone of app, unattended
status queryone of active, lobby
member_id querystringDevices registered by this member.
external_id querystringThe external_id given at enrolment.
name querystringExact 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.

ParameterTypeDescription
device_id required pathstring
  • 200 The device. → Device
  • 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).

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).

ParameterTypeDescription
device_id required pathstring
Idempotency-Key headerstringUnique per logical operation (UUID recommended). Kept 24 hours per key.
Request body application/json
FieldTypeDescription
namestring
roleone of beamin, beamoutBeam-in = can be reached (a target); Beam-out = connects out into the company's devices.
  • 200 The device. → Device
  • 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).
  • 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).

ParameterTypeDescription
device_id required pathstring
Idempotency-Key headerstringUnique 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.

ParameterTypeDescription
limit queryinteger
cursor querystringOpaque 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).

ParameterTypeDescription
Idempotency-Key required headerstringRequired on creating requests. Same key + same body replays; same key + other body -> 422.
Request body application/json
FieldTypeDescription
label requiredstring
external_idstring
hoursintegerDefault 2. 1-24.
  • 201 Created. → EnrolmentCreated
  • 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).
  • 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.

ParameterTypeDescription
enrolment_id required pathstring
  • 200 The enrolment. → Enrolment
  • 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).

DELETE/v1/enrolments/{enrolment_id}

Revoke an unused enrol code connections:write

Scope connections:write.

ParameterTypeDescription
enrolment_id required pathstring
Idempotency-Key headerstringUnique 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.

ParameterTypeDescription
member_id required pathstring
  • 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.

ParameterTypeDescription
member_id required pathstring
Idempotency-Key required headerstringRequired on creating requests. Same key + same body replays; same key + other body -> 422.
Request body · AccessGrantInput application/json
FieldTypeDescription
device_id requiredstring
reach requiredone of network, device_network, device, portsnetwork - 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.
portsarray of integerAt most 32 items.
internetone of none, choice, fullInternet routing through the device.
valid_untilstring (date-time)Grant end.
  • 201 Added. → AccessGrant
  • 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).
  • 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.

ParameterTypeDescription
member_id required pathstring
Idempotency-Key headerstringUnique per logical operation (UUID recommended). Kept 24 hours per key.
Request body application/json
FieldTypeDescription
grants requiredarray of AccessGrantInputAt most 200 items.
  • 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.

ParameterTypeDescription
member_id required pathstring
grant_id required pathstring
Idempotency-Key headerstringUnique 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.

ParameterTypeDescription
limit queryinteger
cursor querystringOpaque cursor from next_cursor of the previous page.
device_id querystring
state queryone of active, paused, expired, revoked
label querystringExact label (case-insensitive).
external_id querystring
  • 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.

ParameterTypeDescription
Idempotency-Key required headerstringRequired on creating requests. Same key + same body replays; same key + other body -> 422.
Request body · BeaminCodeCreate application/json
FieldTypeDescription
device_id requiredstringA Beam-in device of the company.
reach requiredReachWhat 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.
internetone of none, choice, fullUse the device's internet: none never, choice the person decides, full always. Default "none".
expires_atstring (date-time)End of the code. Give this or valid_days; neither = no end (where the plan allows).
valid_daysinteger1-365.
labelstring
external_idstringYour id; unique per company among live codes.
  • 200 Idempotent replay (Idempotent-Replayed: true); without the code. → BeaminCodeCreated
  • 201 Created. → BeaminCodeCreated
  • 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).
  • 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.

ParameterTypeDescription
code_id required pathstringThe code's stable id (bic_...), never the code itself.
  • 200 The code. → BeaminCode
  • 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).

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.

ParameterTypeDescription
code_id required pathstringThe code's stable id (bic_...), never the code itself.
Idempotency-Key headerstringUnique per logical operation (UUID recommended). Kept 24 hours per key.
Request body · BeaminCodePatch application/merge-patch+json
FieldTypeDescription
labelstring
pausedboolean
expires_atstring (date-time)Only earlier than the current end.
external_idstring or null
  • 200 The code. → BeaminCode
  • 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).
  • 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.

ParameterTypeDescription
code_id required pathstringThe code's stable id (bic_...), never the code itself.
Idempotency-Key headerstringUnique 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.

ParameterTypeDescription
code_id required pathstringThe code's stable id (bic_...), never the code itself.
limit queryinteger
cursor querystringOpaque 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.

ParameterTypeDescription
limit queryinteger
cursor querystringOpaque cursor from next_cursor of the previous page.
member_id querystring
device_id querystring
  • 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.

ParameterTypeDescription
Idempotency-Key required headerstringRequired on creating requests. Same key + same body replays; same key + other body -> 422.
Request body · ConnectionGrantCreate application/json
FieldTypeDescription
member_id requiredstring
device_id requiredstring
reach requiredReachWhat 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.
internetone of none, choice, fullUse the device's internet: none never, choice the person decides, full always. Default "none".
valid_untilstring or null (date-time)The grant ends at this instant.
  • 201 Created. → ConnectionGrant
  • 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).
  • 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.

ParameterTypeDescription
grant_id required pathstring
  • 200 The grant. → ConnectionGrant
  • 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).

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.

ParameterTypeDescription
grant_id required pathstring
Idempotency-Key headerstringUnique per logical operation (UUID recommended). Kept 24 hours per key.
Request body · ConnectionGrantPatch application/merge-patch+json
FieldTypeDescription
reachReachWhat 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.
internetone of none, choice, fullUse the device's internet: none never, choice the person decides, full always. Default "none".
valid_untilstring or null (date-time)
  • 200 The grant. → ConnectionGrant
  • 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/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.

ParameterTypeDescription
grant_id required pathstring
Idempotency-Key headerstringUnique 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.

ParameterTypeDescription
limit queryinteger
cursor querystringOpaque cursor from next_cursor of the previous page.
device_id querystring
member_id querystring
via queryone 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
FieldTypeDescription
from requiredstring (date-time)
to requiredstring (date-time)Exclusive; to - from <= 31 days.
filterobject
filter.actorstringActor label, e-mail or api:<key_id>.
filter.actionarray of stringAt most 50 items.
filter.devicestringDevice id.
filter.member_idstring
limitintegerDefault 500. 1-1000.
cursorstring or null
formatone of json, ndjson, csvDefault "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). → AuditPage
  • 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/audit/v1/verify

Verify the audit hash chain for a window audit:read

Scope audit:read. Same window rules as /events.

ParameterTypeDescription
from required querystring (date-time)
to required querystring (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).

Terraform

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.

ResourceWhat it manages
awacino_memberA member account and its first invitation (send_invitation); destroy = offboard. Import by id or external_id:<x>
awacino_invitationA new invitation code for an invited member; destroy = revoke
awacino_beamin_deviceA 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_grantA member's access to one Beam-in device: reach, internet, valid_until
awacino_beamin_codeA 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 callto - from at most 31 days (window_too_large)
How far backThe company's audit retention: Basic 30, Standard 90, Premium 180 days, with Compliance 365 days (outside_retention)
Filtersactor (label, e-mail or api:<key_id>), action[], device, member_id
Formatsjson (default), ndjson (one event per line), csv
Pagingnext_cursor in the body for json, in the X-Next-Cursor header for ndjson and csv
IntegrityEach 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.

KeyId

string

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.

FieldTypeDescription
type requiredstring (uri)
title requiredstring
status requiredinteger
code requiredone 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, internalStable machine code. New codes may be added.
detailstring
request_id requiredstring (uuid)
required_scopeone of users:read, users:write, connections:read, connections:write, audit:readWith insufficient_scope - the section the key is missing.
errorsarray of objectField errors for validation_failed.

ApiKeyInfo

FieldTypeDescription
key_id requiredstring
description requiredstring
scopes requiredarray of one of users:read, users:write, connections:read, connections:write, audit:read
sectionsobjectThe same scopes as the checkboxes of the Awacino API page.
sections.usersone of none, read, write
sections.connectionsone of none, read, write
sections.auditone of none, read
created_at requiredstring (date-time)
expires_at requiredstring (date-time)
ip_allowarray of string
company_id requiredstring

Company

FieldTypeDescription
id requiredstring
name requiredstring
plan requiredone of company_basic, company_standard, company_premium
packages requiredarray of one of management, security, identity, compliance, branding, api_access
seats requiredobject
seats.usedintegerActive members + open invitations.
seats.totalinteger
beamin_devices requiredobject
beamin_devices.usedinteger
beamin_devices.totalinteger
audit_retention_daysone of 30, 90, 180, 365
access_capabilities requiredarray of one of network, device_network, device, ports, internet, valid_untilReach / 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

FieldTypeDescription
id requiredstring
email requiredstring (email)The invited address (the member account's address).
display_namestring or null
external_idstring or nullYour id; unique per company.
role requiredone of main_admin, admin, auditor, user, readKeys may assign user, read and auditor (Compliance). main_admin / admin are read-only here.
status requiredone of invited, active, deactivated, removed
can_automationboolean
can_agenticboolean
created_at requiredstring (date-time)
accepted_atstring or null (date-time)
deactivated_atstring or null (date-time)
created_byobjectWho created the member.
created_by.kindone of user, api_key, scim, partner
created_by.idstring
created_by.labelstring
signed_in_withobject or nullThe identity that redeemed the invitation.
signed_in_with.providerone of apple, google, microsoft, sso
signed_in_with.email_domainstring

MemberCreate

FieldTypeDescription
email requiredstring (email)
display_namestring
external_idstring
roleone of user, read, auditorDefault "read".
can_automationbooleanREAD only; default false.
can_agenticbooleanREAD only; default false.
invitationInvitationRequest
accessarray of AccessGrantInputOptional initial grants (needs Management and connections:write). At most 200 items.

MemberPatch

FieldTypeDescription
roleone of user, read, auditor
can_automationboolean
can_agenticboolean
display_namestring or null
external_idstring or null
activebooleanfalse = deactivate, true = reactivate.

InvitationRequest

FieldTypeDescription
daysintegerDefault 7. 1-14.
send_mailbooleantrue = Awacino mails the invited address. Default false.
localestringMail language (ISO 639-1, e.g. de, nb, pt). Default "en".

Invitation

FieldTypeDescription
codestringSingle-use invitation code. Present only in the first answer.
join_urlstring (uri)https://www.awacino.com/join/#<code> - the code is in the fragment and never reaches a server log.
expires_at requiredstring (date-time)
mailedboolean
code_redactedbooleantrue on an idempotent replay - the code is not stored and cannot be returned again.

InvitationStatus

FieldTypeDescription
state requiredone of open, used, expired, revoked, none
expires_atstring or null (date-time)
used_atstring or null (date-time)

MemberWithInvitation

FieldTypeDescription
id requiredstring
email requiredstring (email)The invited address (the member account's address).
display_namestring or null
external_idstring or nullYour id; unique per company.
role requiredone of main_admin, admin, auditor, user, readKeys may assign user, read and auditor (Compliance). main_admin / admin are read-only here.
status requiredone of invited, active, deactivated, removed
can_automationboolean
can_agenticboolean
created_at requiredstring (date-time)
accepted_atstring or null (date-time)
deactivated_atstring or null (date-time)
created_byobjectWho created the member.
created_by.kindone of user, api_key, scim, partner
created_by.idstring
created_by.labelstring
signed_in_withobject or nullThe identity that redeemed the invitation.
signed_in_with.providerone of apple, google, microsoft, sso
signed_in_with.email_domainstring
invitationInvitation

DeviceRole

one of beamin, beamout

Beam-in = can be reached (a target); Beam-out = connects out into the company's devices.

Device

FieldTypeDescription
id requiredstring
name requiredstring
role requiredone of beamin, beamoutBeam-in = can be reached (a target); Beam-out = connects out into the company's devices.
kind requiredone of app, unattended
status requiredone of active, lobby
platform requiredstring
member_idstring or nullThe member who registered it.
external_idstring or null
first_seenstring (date-time)
last_seenstring or null (date-time)Beam-in devices only; Beam-out devices are passive.

Enrolment

FieldTypeDescription
id requiredstring
label requiredstring
external_idstring or null
expires_at requiredstring (date-time)
state requiredone of open, used, expired, revoked
device_idstring or null

EnrolmentCreated

FieldTypeDescription
id requiredstring
label requiredstring
external_idstring or null
expires_at requiredstring (date-time)
state requiredone of open, used, expired, revoked
device_idstring or null
code requiredstringOne-time enrol code. Returned once.
install requiredobject
install.dockerstringA docker run line.
install.aptstringShell lines for Debian / Ubuntu.
install.cloud_initstringA #cloud-config document.

AccessGrantInput

FieldTypeDescription
device_id requiredstring
reach requiredone of network, device_network, device, portsnetwork - 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.
portsarray of integerAt most 32 items.
internetone of none, choice, fullInternet routing through the device.
valid_untilstring (date-time)Grant end.

AccessGrant

FieldTypeDescription
device_id requiredstring
reach requiredone of network, device_network, device, portsnetwork - 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.
portsarray of integerAt most 32 items.
internetone of none, choice, fullInternet routing through the device.
valid_untilstring (date-time)Grant end.
id requiredstring
created_at requiredstring (date-time)
created_byobject
created_by.kindone of user, api_key, partner
created_by.idstring

AuditQuery

FieldTypeDescription
from requiredstring (date-time)
to requiredstring (date-time)Exclusive; to - from <= 31 days.
filterobject
filter.actorstringActor label, e-mail or api:<key_id>.
filter.actionarray of stringAt most 50 items.
filter.devicestringDevice id.
filter.member_idstring
limitintegerDefault 500. 1-1000.
cursorstring or null
formatone of json, ndjson, csvDefault "json".

AuditEvent

FieldTypeDescription
id requiredstring
chain_seq requiredinteger
created_at requiredstring (date-time)
action requiredstring
actorstring or null
actor_ipstring or null
targetstring or null
target_ipstring or null
device_idstring or null
ended_atstring or null (date-time)
duration_secondsinteger or null
detailsobject or null
prev_hashstring or null
row_hash requiredstring

AuditPage

FieldTypeDescription
data requiredarray of AuditEvent
next_cursor requiredstring or nullPass 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.

FieldTypeDescription
kind requiredone of network, device, ports
portsarray of integerRequired 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

FieldTypeDescription
kindone of user, api_key, scim, partner
idstring
labelstring

BeaminCodeState

one of active, paused, expired, revoked

BeaminCodeCreate

FieldTypeDescription
device_id requiredstringA Beam-in device of the company.
reach requiredReachWhat 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.
internetone of none, choice, fullUse the device's internet: none never, choice the person decides, full always. Default "none".
expires_atstring (date-time)End of the code. Give this or valid_days; neither = no end (where the plan allows).
valid_daysinteger1-365.
labelstring
external_idstringYour id; unique per company among live codes.

BeaminCode

FieldTypeDescription
id requiredstringStable id. Never the code.
device_id requiredstring
device_namestring
labelstring
external_idstring or null
reach requiredReachWhat 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 requiredone of none, choice, fullUse the device's internet: none never, choice the person decides, full always. Default "none".
state requiredone of active, paused, expired, revoked
paused_reasonone of admin, lobby, null
code_hintstringLast 4 characters of the code.
expires_atstring or null (date-time)
bound_deviceobject or nullThe device that redeemed the code first; only it can use the code.
bound_device.labelstring
bound_device.platformone of ios, android, macos, windows, linux, web,
bound_device.bound_atstring (date-time)
usesinteger
last_used_atstring or null (date-time)
created_at requiredstring (date-time)
revoked_atstring or null (date-time)
created_byCreatedBy
clamped_by_planarray of stringWhat the plan changed in the request, for example expires_at or internet.

BeaminCodeCreated

FieldTypeDescription
id requiredstringStable id. Never the code.
device_id requiredstring
device_namestring
labelstring
external_idstring or null
reach requiredReachWhat 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 requiredone of none, choice, fullUse the device's internet: none never, choice the person decides, full always. Default "none".
state requiredone of active, paused, expired, revoked
paused_reasonone of admin, lobby, null
code_hintstringLast 4 characters of the code.
expires_atstring or null (date-time)
bound_deviceobject or nullThe device that redeemed the code first; only it can use the code.
bound_device.labelstring
bound_device.platformone of ios, android, macos, windows, linux, web,
bound_device.bound_atstring (date-time)
usesinteger
last_used_atstring or null (date-time)
created_at requiredstring (date-time)
revoked_atstring or null (date-time)
created_byCreatedBy
clamped_by_planarray of stringWhat the plan changed in the request, for example expires_at or internet.
codestringThe Beam-in code. Present only in the first answer.
connect_urlstring (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_redactedbooleantrue on an idempotent replay - create a new code if the first answer was lost.

BeaminCodePatch

FieldTypeDescription
labelstring
pausedboolean
expires_atstring (date-time)Only earlier than the current end.
external_idstring or null

CodeSession

FieldTypeDescription
id requiredstring
peer_labelstringName the connecting device reported.
peer_platformone of ios, android, macos, windows, linux, web,
portinteger or null
connected_at requiredstring (date-time)
disconnected_atstring or null (date-time)
duration_secondsinteger or null

ConnectionGrantCreate

FieldTypeDescription
member_id requiredstring
device_id requiredstring
reach requiredReachWhat 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.
internetone of none, choice, fullUse the device's internet: none never, choice the person decides, full always. Default "none".
valid_untilstring or null (date-time)The grant ends at this instant.

ConnectionGrantPatch

FieldTypeDescription
reachReachWhat 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.
internetone of none, choice, fullUse the device's internet: none never, choice the person decides, full always. Default "none".
valid_untilstring or null (date-time)

ConnectionGrant

FieldTypeDescription
member_id requiredstring
device_id requiredstring
reach requiredReachWhat 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.
internetone of none, choice, fullUse the device's internet: none never, choice the person decides, full always. Default "none".
valid_untilstring or null (date-time)The grant ends at this instant.
id requiredstring
state requiredone of active, expired
created_at requiredstring (date-time)
created_byCreatedBy

ActiveConnection

FieldTypeDescription
id requiredstring
device_id requiredstringThe Beam-in device that is reached.
device_namestring
via requiredone of member, own_device, beamin_code
member_idstring or null
code_idstring or null
code_labelstring or null
peer_namestringName of the connecting device.
peer_platformone of ios, android, macos, windows, linux, web,
since requiredstring (date-time)

Download and support