Invitations

Invitations are how an organization adds team members without sharing a login. Every resource in WarpLink sits under an organization, and every organization has a roster of members with a role: owner, admin, or member. Creating an invitation reserves a seat and emails the invitee a link; the invitation itself is not membership. Membership only exists once the invitee accepts, which happens through the emailed link on the dashboard, not through this API. Until that happens, the invitation sits in a pending state that this endpoint set can create, list, and revoke.

An invitation is scoped to one organization and one email address, and it carries the role the invitee will hold once they accept: admin or member. There is no owner option here. Ownership transfers through a separate dashboard flow, not through the invitation path, because an org can have exactly one owner at a time and inviting a second one would be a contradiction. An admin can manage links, apps, and the team roster (short of removing an owner); a member can pause and resume any link, edits and deletes only the links they created, creates and edits apps, and reads analytics. Deleting an app and managing custom domains stay with owners and admins. See the role-permission matrix below for exactly which operations each role can reach.

Authentication and Permissions

Every invitation request authenticates with a Bearer API key and needs the scope for the operation:

Operation	Scope	Role required (dashboard-created keys)
Create an invitation	team:write	owner or admin (team:manage)
List invitations	team:read	owner or admin (team:manage)
Revoke an invitation	team:write	owner or admin (team:manage)

The scope check and the role check are independent, and both run on every one of these three operations, including the read. A key that only has team:read is checked against the same team:manage permission a team:write key would need, because the permission matrix in permissions.ts grants team:manage to owner and admin only. A member role never has team:manage, so a key created by a member is refused with 403 FORBIDDEN even for listing invitations, regardless of which scopes the key carries. This mirrors the dashboard UI, where team management is an admin-and-above surface. The role check only applies to keys that carry a created_by, which is how the dashboard tags keys created through its own UI. A key created without that context skips the role check and is authorized on scope alone; see Authentication for how that distinction works end to end.

Plan Limits

Invitations consume the organization's member seat limit, which is a plan-level number, not a per-invitation setting:

Plan	Member limit
Free	1
Starter	3
Growth	10
Scale	Unlimited
Unlimited	Unlimited

The Free plan's limit of 1 means the org itself is the only seat, so team invitations are refused outright with 403 SEAT_LIMIT_EXCEEDED before the server even counts current members. Every plan above Free enforces the same limit the other way: the server counts active seats (accepted members plus any invitations still pending) and refuses a new invitation with the same 403 SEAT_LIMIT_EXCEEDED code once the count reaches the plan's memberLimit. Revoking a stale invitation, or upgrading the plan, frees a seat immediately. The server also auto-revokes any invitation to that same email address that has already passed its expiry, so a re-invite doesn't collide with the old one.

Validation and Behavior

• email must be a valid email address, up to 255 characters.
• role must be admin or member. Any other value, including owner, fails validation with 400 VALIDATION_ERROR.
• Invitations expire 7 days after creation. There is no option to set a longer or shorter window.
• An email already holding active membership in the organization is refused with 409 ALREADY_MEMBER, checked before the seat limit.
• An email with an existing, still-active invitation to the same organization is refused with 409 DUPLICATE_INVITATION. This is enforced at the database level as a unique constraint, not just an application check, so it holds even under concurrent requests.
• Sending the invitation email is fire-and-forget: the invitation row is created and returned first, and the email dispatch happens after. A delivery failure never turns a successful 201 into an error, and never rolls back the created invitation.
• Acceptance is not part of this API. The email links to a dashboard page (/invitations/accept) that validates the token, checks the same expiry and state rules described below, and adds the member. There is no POST /v1/invitations/{id}/accept endpoint to script against.

Create an Invitation

The response is the created invitation, including its token. This is the only response in this API that returns the token; keep it if you're building your own acceptance flow, since the dashboard's emailed link is the only other place it appears.

List Invitations

Results default to status=pending. Pass status=all to see accepted, revoked, and expired invitations alongside pending ones, or filter to exactly one of those states. List items never include the token field, so listing invitations is safe to log or display without leaking the acceptance credential; only the single-invitation response from creating or revoking one carries it.

Revoke an Invitation

Revoking is the only way to cancel a pending invitation early and free its seat before the 7-day window closes on its own. An invitation can only be revoked while it is still pending; the endpoint checks the invitation's current state before acting and refuses with a 400 naming exactly which state it's in.

Worked Example

Invite a new admin, list pending invitations, then revoke one that's no longer needed:

curl -X POST https://api.warplink.app/v1/invitations \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "teammate@example.com", "role": "admin" }'

{
  "id": "8f1c2e40-...",
  "org_id": "3a9d1e20-...",
  "email": "teammate@example.com",
  "role": "admin",
  "invited_by": "1b2c3d40-...",
  "token": "9f86d081884c7d659a2feaa0c55ad015...",
  "expires_at": "2026-09-23T12:00:00.000Z",
  "accepted_at": null,
  "revoked_at": null,
  "created_at": "2026-09-16T12:00:00.000Z",
  "updated_at": "2026-09-16T12:00:00.000Z"
}

curl "https://api.warplink.app/v1/invitations?status=pending&limit=20" \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY"

{
  "data": [
    {
      "id": "8f1c2e40-...",
      "org_id": "3a9d1e20-...",
      "email": "teammate@example.com",
      "role": "admin",
      "invited_by": "1b2c3d40-...",
      "expires_at": "2026-09-23T12:00:00.000Z",
      "accepted_at": null,
      "revoked_at": null,
      "created_at": "2026-09-16T12:00:00.000Z",
      "updated_at": "2026-09-16T12:00:00.000Z"
    }
  ],
  "pagination": { "total": 1, "limit": 20, "offset": 0, "has_more": false }
}

curl -X DELETE https://api.warplink.app/v1/invitations/8f1c2e40-... \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY"

The revoke response echoes the invitation with revoked_at set to the current time and role unchanged, so a caller scripting cleanup can confirm which invitation it just canceled without a follow-up read.

Common Errors

Status	Code	Cause
400	VALIDATION_ERROR	email isn't a valid address, or role isn't admin or member
400	INVALID_ID	The id path parameter isn't a valid UUID
400	INVITATION_ALREADY_ACCEPTED	Revoking an invitation the invitee already accepted
400	INVITATION_ALREADY_REVOKED	Revoking an invitation that was already revoked
400	INVITATION_EXPIRED	Revoking an invitation past its 7-day window
403	FORBIDDEN	The key lacks the scope, or its creator's role lacks team:manage
403	SEAT_LIMIT_EXCEEDED	The plan's member limit is reached, or the plan doesn't support invitations at all
404	NOT_FOUND	No invitation with that ID exists in this organization
409	ALREADY_MEMBER	That email already belongs to a member of the organization
409	DUPLICATE_INVITATION	That email already has an active, unrevoked invitation

FAQ

Can I invite someone as an owner? No. role only accepts admin or member. Ownership moves through a separate transfer flow with exactly one owner at a time, never through an invitation.

What happens to the seat if nobody accepts within 7 days? The invitation stops counting toward the seat limit as soon as it expires; revoking it (explicitly, or automatically the next time someone invites that same email) just clears the stale row so a re-invite doesn't collide with it. An expired invitation that nobody revokes still occupies a "pending" row, but a fresh invite attempt to the same address triggers the auto-revoke and clears it.

Does revoking an invitation remove an existing team member? No. Revoking only cancels a pending invitation before it's accepted. Removing an existing member is a separate team-management operation, not exposed on this endpoint.

Why did my request fail with SEAT_LIMIT_EXCEEDED even though I have open seats? On the Free plan, the member limit is 1, which is the org's own seat. That plan blocks invitations outright rather than counting toward a limit greater than one, so the fix is upgrading rather than freeing a seat.

Can a member role create or list invitations? No, even with a key scoped team:read or team:write. Managing the team, including reading the pending list, requires the team:manage permission, which only owner and admin roles hold.