Access and guests

Read the access policy of an application, invite external guests with expiring application-scoped grants, and revoke them.

  • Availability: Planned
  • Evidence: Read from source
  • Reference

Operations

Operation Request Capability Retry
access.read GET /v1/applications/{application}/access access.manage
access.invite POST /v1/applications/{application}/access/guests access.manage key
access.revoke DELETE /v1/applications/{application}/access/guests/{grant} access.manage natural
access.tickets.create POST /v1/applications/{application}/access/tickets application.read natural

Visibility itself is a member of the application; change it with applications.change. Private applications require the private_apps entitlement, which a platform operator enables manually.

The access policy

Member Meaning
visibility public or private
members Always organization: every member of the owning organization with application.read may open a private application
guests The guest grants
revocation.bound Milliseconds after which a revoked grant no longer reaches restricted content

Invite a guest

A guest is a person outside the organization. A guest grant is scoped to one application. It is not an account, a membership or a registry credential, and it never reaches the management API.

Member Required Rule
label Yes Up to 120 characters; who the grant is for
email No
lifetime No Milliseconds until expiry, at least 60000. The configured default applies when absent, and the configured maximum bounds it. Every grant expires.
JSON
{ "label": "Design review, Ana", "lifetime": 259200000 }

The answer is the only one that carries the token:

Member Meaning
grant The grant: id, label, state (active, expired, revoked), created, expires
token The guest token. The CDN stores only its hash and cannot show it again.
url The invitation link for the guest

A retry with the same Idempotency-Key answers the same grant with a newly rotated token, because the original token cannot be recovered. An application whose state does not allow guest grants answers 409 STATE_INVALID, and an organization without the private_apps entitlement answers 403 ENTITLEMENT_REQUIRED.

Open a private application as a member

A member does not use a guest grant. access.tickets.create confirms that the caller is a member who may read the application and answers a one-time member ticket:

Member Meaning
ticket Single use. The CDN stores only its hash and cannot show it again.
expires When the unused ticket stops being exchangeable
url The link that opens the application with the ticket in the URL fragment. It is absolute when the application has a reserved or verified domain, and origin-relative otherwise.
window Milliseconds the confirmation of membership stays valid. Ask for a ticket again within it while the application stays open.

The ticket is bound to this one application and its host. It grants no management right, and the management API never accepts it. The application's own host exchanges it for that host's access cookie, as Private access describes. An application whose state has no private delivery answers 409 STATE_INVALID.

An interface that keeps a private application open, such as the CDN administration, asks for a new ticket inside window. When the membership ends, the authority refuses the next confirmation and access runs out within the revocation bound.

Revoke

access.revoke answers the revoked grant. Revocation takes effect on HTML and on every restricted resource, cached paths included, within revocation.bound. Open realtime subscriptions of the affected person are closed as well.

How delivery answers a request without access, or with a revoked grant, is covered in Private access.