Skip to content

Telescope access grants

A TelescopeAccessGrant admits an entity — a user or an organization — to observe with a telescope. It is the record that says “this entity may schedule observations here,” and it carries the entity’s shares: its relative weight on the telescope. It does not transfer ownership, and it does not let the grantee configure or operate the telescope.

The umbrella for this and the rest of the access model is Telescope access; this page goes deeper on grants specifically.

A telescope access grant on its own reaches no queue. What it authorizes is defined by the queue access grants (ObservingQueueAccessGrant) that hang off it, one per queue the entity may use. Together they let the grantee build observing accounts that reach those queues; see Observing queues.

A grant carries:

  • shares — the entity’s relative weight on the telescope (default 1). Shares are relative within one telescope, so 80 / 10 / 10 reads as percentages. Shares are meant to drive fair-share prioritization, which is not live yet; today they are recorded and shown, but do not change the schedule.
  • timeUsed — credits spent through this grant across all of the telescope’s queues.
  • revoked — whether the grant has been revoked.

An entity holds at most one telescope access grant per telescope.

Grants to observe are independent of authority to operate. A collaborator can be allowed to consume time on a telescope (a telescope access grant) without being able to configure it, and configuring a telescope requires no access grant.

Ownership is a single owner on the telescope record — an organization or a user. Authority to view, configure, and manage the telescope comes from ownership and, inside an owning organization, from organization roles: the owner and device manager roles manage every telescope the organization owns (configuration, queues, and access grants), and the telescope viewer role can view the telescope pages without changing anything. See Roles and permissions.

The owner observes through a telescope access grant like everyone else. When Skynet staff set up a newly registered telescope, it gets the owner’s grant (80 shares), a grant to Skynet (10 shares), and a grant to the Skynet Telescope Exchange organization (10 shares); a Skynet-owned telescope gets only the owner grant. These are a starting point: the owner can change the shares or revoke any of them.

The owner-facing surface for grants is the telescope’s Access Grants tab, where you add a grantee, choose their queues, set their shares, edit, and revoke.

In the API, grants are managed under the telescope (the telescope path segment accepts its UID or slug):

GET /v1/telescopes/{telescope}/access-grants
POST /v1/telescopes/{telescope}/access-grants
GET /v1/telescopes/{telescope}/access-grants/{grant_uid}
PATCH /v1/telescopes/{telescope}/access-grants/{grant_uid}
DELETE /v1/telescopes/{telescope}/access-grants/{grant_uid}

POST takes shares, the queueUids to grant, and either an entityUid or an invitation; PATCH changes shares. DELETE revokes: queue access grants that observing accounts still reference are marked revoked rather than deleted, and the telescope access grant goes with them. A cross-telescope listing — grants on telescopes you manage plus grants held by you or organizations you manage observing for — is at GET /v1/telescope-access-grants.

You can name directly yourself, a user you can find in the directory, or an organization you administer. Anyone else is reached by an email invitation — see the TelescopeAccessGrantInvitation companion record. The grant exists with no grantee until the invitation is accepted, at which point it binds to the accepting entity. An invitation can also be addressed to a specific organization: then it can only be accepted on that organization’s behalf, by one of its administrators. This lets you provision a grant for someone who hasn’t joined Skynet yet, or reach an organization you don’t administer without binding it behind its back.