Skip to main content

Invitations

An invitation asks a person by email to join the workspace with grants; create, send or withdraw one.

Invitation object​

An invitation asks a person, by email, to join the workspace with the grants it lists once they accept.

iduuidrequired

The invitation's id.

emailemailrequired

The email address invited.

grantsarray of Grant or nullrequired

The grants the person holds once they accept, those you are shown.

other_grantsbooleanrequired

True when the invitation carries a grant you are not shown.

created_atdate-timerequired

When the invitation was created.

updated_atdate-timerequired

When the invitation last changed.

last_sent_atdate-time or nullrequired

When the invitation email was last sent; null when it never was.

expires_atdate-timerequired

When the invitation stops being valid. Sending it again moves this later.

invited_by_user_idstring or nullrequired

The user id of the member who sent the invitation. Null when no sender is recorded, when the sender has left, or when you are not shown them.

sender_removedbooleanrequired

Whether the recorded sender is no longer a member.

List invitations​

GET/workspaces/{workspace_id}/invitations
Preview

Returns the workspace's pending invitations, each with the grants it carries, a page at a time, oldest first. Needs member.read; you see the invitations whose grants your reach contains, and every one you sent.

curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of admin:readadmin:write
Privilege
member.read

Needs member.read. member.read applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.

Behavior

Retry
Safe to send again
Paging
Cursor · 1000 a page by default, up to 5000

Path parameters

workspace_iduuidrequired

The workspace's id.

Query parameters

emailstring

Only invitations to this email address. One you are not shown answers an empty page, as one never sent does. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.

limitinteger

How many invitations a page holds: 1 to 5000, 1000 by default.

Default: 10001 to 5000

cursorstring

The next_cursor of the previous page, with the same filters.

Response 200

invitationsarray of Invitationrequired

The pending invitations you are shown, oldest first.

next_cursorstring or nullrequired

Null on the last page. Otherwise pass it as cursor, with the same filters, for the next page.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, or one given twice.No
400APP_API_ERR_BAD_PARAMETERSA filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; parameter names the filter.No
400APP_API_ERR_BAD_PARAMETERSlimit is not 1 to 5000, or cursor cannot be read or was sent with other filters.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold member.read. The same refusal comes when the path names a workspace other than the token's own.No

Plus the errors every call can return.

Related

Invite a person​

POST/workspaces/{workspace_id}/invitations
Preview

Invites an email address to the workspace with the grants it holds once accepted, or saves a pending invitation again: the one invitation_id names, or with invitation_id left out the email's own. Sending the same invitation_id again saves the same invitation, so a retry is safe. It returns 409 for an email that belongs to a member, whether or not you can see them, for an email with a pending invitation under a different invitation_id, and, with invitation_id left out, for one whose pending invitation carries grants you may not change. Needs member.manage, and each grant must sit inside what you may grant. Saving does not send the email; sending it is its own call.

curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "email": "casey.nguyen@example.com",    "grants": [      {        "role_id": "analyst",        "scope": {          "kind": "selected",          "org_ids": [            "0a9e0000-0000-4000-8000-000000000103"          ]        }      }    ],    "invitation_id": "1a7e0000-0000-4000-8000-000000000601"  }'

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
admin:write
Privilege
member.manage

Needs member.manage. member.manage applies at each organization a grant covers and every organization below it.

Behavior

Retry
Read before sending again
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

Request body

emailemailrequired

The email address to invite. Required.

grantsarray of GrantRequestrequired

The grants the person holds once they accept. An empty list invites with none, which needs member.manage over every organization. Required.

invitation_iduuid or null

The invitation to save again, or the id to give a new one: a UUID, which you may choose. Left out, the email's pending invitation is saved again, or a new one is given a new id. A different id for an email with a pending invitation returns 409.

Response 200

iduuidrequired

The id of the row the call created or changed.

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.No
400APP_API_ERR_MISSING_PARAMETERemail is empty, grants is left out or null, or a grant names no role.No
400APP_API_ERR_BAD_PARAMETERSemail holds no @, invitation_id is not a UUID, or a grant names a role the workspace does not have, or a malformed scope.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold member.manage. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_BEYOND_OWN_AUTHORITYtoken_scopeThe grants reach beyond what you may grant, grants is empty and you do not hold member.manage over every organization, or the invitation saved again carries grants beyond your reach. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No
404APP_API_ERR_RECORD_NOT_FOUNDinvitation_id names an invitation of another workspace, or one you cannot see.No
409APP_API_ERR_INVITATION_EMAIL_TAKENThe email belongs to a member, whether or not you can see them, a deleted account still in the workspace included; or it has a pending invitation and the body names a different invitation_id, or names none and that invitation carries grants you may not change.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Withdraw an invitation​

DELETE/workspaces/{workspace_id}/invitations/{id}
PreviewDestructive

Withdraws a pending invitation, so it can no longer be accepted. Needs member.manage, and the invitation's grants must sit inside your reach.

curl -X DELETE \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
admin:write
Privilege
member.manage

Needs member.manage. member.manage applies at each organization a grant covers and every organization below it.

Behavior

Retry
Safe to repeat: ends in the same state
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The invitation's id.

Response 200

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, or one given twice.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe request carries a body other than nothing, null or {}: a delete takes none, and its options are query parameters; parameter names the body's first field, or body.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold member.manage. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_BEYOND_OWN_AUTHORITYtoken_scopeThe invitation carries grants beyond your reach. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No
404APP_API_ERR_RECORD_NOT_FOUNDNo such pending invitation, or one you cannot see.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Send an invitation email​

POST/workspaces/{workspace_id}/invitations/{id}/send
Preview

Sends, or sends again, the email of a pending invitation, and moves its expiry 90 days out. Needs member.manage. Each API token may send 500 every 5 minutes, and a signed-in person 5 every 30 seconds; a send past that returns 429 with Retry-After.

curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601/send" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
admin:write
Privilege
member.manage

Needs member.manage. member.manage applies at each organization a grant covers and every organization below it.

Behavior

Retry
Read before sending again
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The invitation's id.

Response 200

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, or names a field: the call takes none.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold member.manage. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_BEYOND_OWN_AUTHORITYtoken_scopeThe invitation carries grants beyond your reach. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No
404APP_API_ERR_RECORD_NOT_FOUNDNo such pending invitation in the workspace, checked before your privilege.No
409APP_API_ERR_CONFLICTThe invitation was declined.Read first
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No
429APP_API_ERR_TOO_MANY_REQUESTSsend_limitYou sent more invitations than the send limit allows (cause send_limit); Retry-After says when to try again.After Retry-After

Plus the errors every call can return.

Related