Invite an email to join an organization

POST/api/orgs/{org}/invites

createOrgInvite

Generates a single-use bearer token for an email + role. The raw token is returned in the response payload exactly once — the inviter passes it to the recipient out of band. (Email integration is a follow-up.) Re-inviting the same email rotates the token; the previous one is revoked.

Requires authentication using a bearer token or a session cookie — see tokens and scopes.

curl

curl -X POST 'https://neosource.dev/api/orgs/ORG/invites' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"email":"string"}'

fetch

fetch("https://neosource.dev/api/orgs/ORG/invites", {
  method: "POST",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"email":"string"}),
});

Path parameters

orgrequired: Organization slug.
string

Request bodyrequired

application/json

CreateOrgInviteRequest

object

emailrequired: string
Email address to invite. Stored case-folded.
role: one of
null
WorkspaceRole
string
Workspace membership role. Ordered low → high (`Member < Admin < Owner`) so that `if actor_role >= WorkspaceRole::Admin` reads naturally.
"member""admin""owner"
ttl_seconds: integer | nullint64
Optional override for time-to-live in seconds. Defaults to 7 days. Capped server-side at 30 days.

Responses

201Invite created

application/json

OrgInviteResponse

object

created_atrequired: integerint64
created_byrequired: string
emailrequired: string
expires_atrequired: integerint64
invite_idrequired: string
org_slugrequired: string
Org slug (so the SPA doesn't need a second lookup to render).
rolerequired: WorkspaceRole
string
Workspace membership role. Ordered low → high (`Member < Admin < Owner`) so that `if actor_role >= WorkspaceRole::Admin` reads naturally.
"member""admin""owner"
token: string | null
Present only on `createOrgInvite` — the bearer the inviter passes to the recipient. Subsequent reads omit it.
workspace_idrequired: string

403Forbidden — one of: forbidden, needs_scope

application/json

one of

ErrorForbidden
NeedsScopeError
object
`403` body returned when listing private repos but the linked identity lacks the required provider scope. The SPA turns this into an incremental-authorization prompt (Tier 2) that calls the `/elevate` OAuth endpoint with this `scope`.
errorrequired
string
Always `needs_scope` — this body exists to carry the extra fields that kind needs.
"needs_scope"
scoperequired
string
The provider scope to request via elevation (e.g. `"repo"`).

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bad Request — one of: invalid_input
401Authentication required
404Not Found — one of: not_found
409Conflict — one of: already_exists, conflict
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget