Invite people#

Adding someone works the same way wherever you do it: an environment's People, a workspace's People, the organisation's Members, or a deployment shared with people. You type a name or an address; if the person is not in the organisation or the workspace yet, one invitation carries everything they will get — the organisation, the workspace with a role, and the environment — and they are added when they accept.

Before you begin#

Who may invite. What you can give depends on your role:

You are	You may invite someone to
Organisation owner or admin	The organisation (as `member` or `admin`), any workspace, any environment
Workspace admin (not an organisation admin)	Your workspace (any workspace role), and so the organisation as a `member` — unless the organisation turned this off
An environment's owner (an editor)	The environment, for people already in the workspace; someone new needs a workspace admin
Workspace editor, viewer, auditor, organisation member	Nobody new

Nobody can give more than they have: a workspace admin cannot make someone an organisation admin, and only someone who may share an environment can put it in an invitation.

In the API examples, ASTRALYX_API is https://api.astralyx.cloud/v1, ASTRALYX_TOKEN an API token for all your workspaces (see API tokens and automation), and <org> and <workspace> your organisation's and workspace's short names.

Who is suggested#

As you type, the console suggests only people you already have something to do with, newest first, each with why:

Shown as	Who
in workspace Vision	People in a workspace you are in
in Acme	Members of an organisation you are in
shared chat with you, you shared chat with them	People who shared a deployment with you, or you with them
invited you, you invited them	People from invitations between you

Nobody else is ever suggested or found, however much of their address you type. To add someone new, type their full address: it is accepted as written, and the console never says whether that address has an account. You can paste several addresses at once, separated by commas, semicolons, spaces or new lines (at most 50).

Company directory

Suggesting everyone with a verified address at your company's domain needs a verified domain, which organisations cannot set up yet. The setting is shown in Organisation → Settings → People, off.

Add someone to an environment#

ConsoleAPI

Open Hesperus → Environments and the environment.
Under People, select Add people.
Type a name or an address, and pick the person. Paste several addresses to add them all.
If everyone is already an editor or admin of the workspace, select Add: they are added at once and told in their notifications.
Otherwise choose their Role in <workspace> (editor is preselected), select Continue, and read the confirmation. It says for each person what they will get, for example:

[email protected] is not in Acme. Adding: Acme as a member, workspace Vision as an editor, and the environment dev-box.

Select Invite. The dialog lists who was added now and who was invited.

$ curl -sS -X POST "$ASTRALYX_API/organizations/<org>/invitations" \
    -H "Authorization: Bearer $ASTRALYX_TOKEN" -H "Content-Type: application/json" \
    -d '{"to": ["<email>"], "workspace": {"slug": "<workspace>", "role": "editor"},
         "grants": [{"kind": "runtime", "cluster": "<cluster>", "name": "dev-box"}]}'
{"items":[{"id":"0192f3c4-…","email":"[email protected]","role":"member","state":"pending","expires_at":"…",
  "workspace":{"slug":"vision","name":"Vision","role":"editor"},
  "grants":[{"kind":"runtime","cluster":"dc1","name":"dev-box","label":"environment"}]}]}

A person already in the workspace as an editor or admin does not need an invitation: share the environment with them directly (Share an environment).

Viewers and auditors of a workspace reach no environment: someone you add to an environment joins the workspace as an editor or admin.

Add someone to a workspace#

ConsoleAPI

Open the workspace, then Settings.
Under People, select Add people.
Pick or type the people, choose their Role in <workspace> (editor, viewer, admin or auditor), select Continue, then Invite.

Invitations still to be answered are listed under Invited, not answered yet, with what each adds and who invited.

$ curl -sS -X POST "$ASTRALYX_API/organizations/<org>/invitations" \
    -H "Authorization: Bearer $ASTRALYX_TOKEN" -H "Content-Type: application/json" \
    -d '{"to": ["<email>", "<email>"], "workspace": {"slug": "<workspace>", "role": "viewer"}}'

Someone who is in the workspace with that role or a higher one already comes back with "state": "member", and nothing is sent.

Add someone to the organisation only#

ConsoleAPI

Open Organisation → Members and select Invite.
Pick or type the people and choose Role in <organisation>: member (sees the workspaces they are added to) or admin (manages clusters, workspaces and people).
Select Continue, then Invite.

$ curl -sS -X POST "$ASTRALYX_API/organizations/<org>/invitations" \
    -H "Authorization: Bearer $ASTRALYX_TOKEN" -H "Content-Type: application/json" \
    -d '{"email": "<email>", "role": "member"}'

What the invited person sees#

They have an account with that address (verified): they are asked in the console — the bell in the top bar shows an invitation with Accept and Decline, and saying what they would join. No e-mail is sent. If it is still unread after a day, they get one reminder by e-mail, unless they turned invitation e-mails off (Notifications).
They have no account: they get an e-mail from Astralyx, <you> invited you to Astralyx, with a link valid for 7 days. They sign up with that address, open the link and select Accept.

Either way, you see the same thing: the invitation, pending.

When they accept, they join the organisation and the workspace at once. Then the environment is shared with them, as you, with your role at that moment: if you have since lost the right to share it, or it was deleted, they stay members of the organisation and workspace, and both of you are told what could not be given. When they decline, nothing is added and you are told.

A role they already have is never lowered by an invitation: someone who is an admin of the workspace stays one.

Answer an invitation#

ConsoleAPI

Select the bell in the top bar (or open Notifications): an invitation shows Accept and Decline. Accepting opens the workspace you joined. An e-mailed link opens Accept the invitation: check the address you are signed in with, then select Accept.

$ curl -sS "$ASTRALYX_API/me/invitations" -H "Authorization: Bearer $ASTRALYX_TOKEN"
{"items":[{"id":"0192f3c4-…","org":{"slug":"acme","name":"Acme"},"role":"member",
  "workspace":{"slug":"vision","name":"Vision","role":"editor"},"grants":[…],
  "invited_by":{"name":"Ana Lima","email":"[email protected]"},"expires_at":"…"}]}
$ curl -sS -X POST "$ASTRALYX_API/me/invitations/0192f3c4-…/accept" -H "Authorization: Bearer $ASTRALYX_TOKEN"
{"org":"acme","role":"member","workspace":"vision","workspace_role":"editor",
 "grants":[{"kind":"runtime","cluster":"dc1","name":"dev-box","label":"environment","ok":true}]}

POST /me/invitations/{id}/decline declines (204). An e-mailed link's token is accepted with POST /invitations/accept {"token": "…"}.

Follow up#

You see	It means	What to do
The invitation under Invited, not answered yet	Still to be answered; it expires 7 days after it was sent.	Wait, or Resend.
e-mail on its way	The e-mail is being sent; delivery is retried for a few hours if the mail server refuses it.	Nothing.
e-mail not delivered · resend	Every attempt failed (a typo, a mailbox that does not exist). You also get a notification.	Check the address; select resend, or Withdraw and invite the right address.

Resend renews the invitation for 7 more days. An address is e-mailed a new link (the old one stops working); an account is asked again in the console. Once every 10 minutes.
Withdraw removes it: its link stops working and it leaves the person's notifications.

The organisation's admins, the workspace's admins and whoever invited may resend or withdraw an invitation.

Who may bring new people in#

By default, a workspace's admins may invite people who are not in the organisation yet: they join it as members, with that workspace. To keep this to the organisation's owners and admins:

ConsoleAPI

Open Organisation → Settings. Under People, clear Workspace admins may invite new people.

$ curl -sS -X PUT "$ASTRALYX_API/organizations/<org>/people-settings" \
    -H "Authorization: Bearer $ASTRALYX_TOKEN" -H "Content-Type: application/json" \
    -d '{"workspace_admins_invite": false}'
{"workspace_admins_invite":false,"company_directory":false,"company_directory_available":false}

Errors#

Error	Cause
`400 INVALID_EMAIL`	Not an e-mail address, a domain (`@acme.example`), or more than 50 at once.
`400 INVALID_ROLE`	Not `member` or `admin` in the organisation, or not a workspace role.
`400 INVITE_SELF`	Your own address.
`400 WORKSPACE_REQUIRED`	An environment without its workspace.
`403 ORG_ADMIN_REQUIRED`	Inviting to the organisation alone, or as an admin, without being an owner or admin; or the organisation keeps new people to its admins.
`403 WORKSPACE_ADMIN_REQUIRED`	Inviting to a workspace without being its admin.
`403 RUNTIME_SHARE_FORBIDDEN`	The environment is not yours to share.
`404 RUNTIME_NOT_FOUND`	No such environment or runtime in the workspace.
`409 INVITATION_EXPIRED`	Accepting after 7 days: ask for a new one.
`409 INVITATION_ANSWERED`	Accepted or declined already.
`429 RESEND_TOO_SOON`	Sent less than 10 minutes ago.

Invite people#

Before you begin#

Who is suggested#

Add someone to an environment#

Add someone to a workspace#

Add someone to the organisation only#

What the invited person sees#

Answer an invitation#

Follow up#

Who may bring new people in#

Errors#

Related#