Skip to main content
Concept · access

Use when

A command is refused or held, a read comes back smaller than expected, or you must say who you act as.

Looking for something else?

The approval of one held change (card Approval). The part of a project a View shows (card View). Choosing the project (card Project).

​
For

Every call acts as one credential. There are three kinds.
  • Session. A person who signed in with penumbra login. A session acts as that person with their project role. Nothing it does waits for approval.
  • Key. A project API key. It reaches one project, holds the scopes its creator chose, and is sent as PENUMBRA_TOKEN.
  • Connection. An agent that a person approved with penumbra connect or on the connect page. It is “my assistant, as me”: it acts for that person, with the scopes the person chose, never above their role.
Role, scopes and a View decide the result. The role comes from the project. The scopes come from the key or the connection. A View, when one limits the credential, narrows what it reads and makes it read-only.

​
Use when

  • A command was refused, or held for approval, and you need to know why.
  • You read less than the person says is there.
  • The person asks who you act as, or what you may do.
  • You plan work for a key or agent, and some of it needs a person’s session.

​
Not this

  • A change that returned pending: follow it (card Approval).
  • Which project a command runs in: card Project.
  • Building the part of the project a client may read: card View.

​
Rules

  1. credential.1 Name your credential before you plan around it. Your job: run penumbra whoami. It prints the kind: session, key or connection. It prints where the CLI took it from, the project and the expiry. For a key it prints only the last four characters. It prints neither your role nor a View.
  2. credential.2 The CLI picks one credential in this order: --token, then PENUMBRA_TOKEN, then the profile’s stored login or connection. Your job: when you act as the wrong party, read the source line of penumbra whoami. A key left in PENUMBRA_TOKEN hides a stored login.
  3. credential.3 Three commands answer three questions. Your job: run penumbra status for your role and for each command group that your credential limits. Run penumbra access me for the View that limits you. Run penumbra status --explain "<command>" for one command. The status command does not show a View, and penumbra access me does not show a role. For a View command such as penumbra context slice publish, penumbra status --explain reports neither a missing scope nor a wait for approval.
  4. credential.4 Some work needs a person’s own session. Enforced: a key or connection that manages keys, access or Brains is refused with human_session_required. Your job: run penumbra status --explain "<command>" first. It says that a session is needed for commands on access, Brains and Kits. It does not say so for commands on keys.
  5. credential.5 A key holds the scopes given when it was created, and its secret is shown once. Enforced: a call that needs a scope the key lacks is refused with “This API key does not have the <scope> scope”. The text also names the command that makes a key with it. Your job: keep the secret out of logs and files. A lost secret cannot be read again, so revoke the key and make a new one. To get a scope the key lacks, make another key with every scope you need. A door that cannot name the scope can still refuse with “This API key is not active”. Read the key’s scopes in penumbra keys list before you decide that it was revoked.
  6. credential.6 A connection never holds more than its person. Enforced: a scope above the person’s role is refused with scope_above_role. A viewer may grant read scopes only. An editor may add the write scopes an editor uses. Owners and admins have no cap. Removing the person, or lowering their role, revokes the connection.
  7. credential.7 A person’s View limit follows the person’s agents. Enforced: a connection that a limited client approved reads through the client’s View, live. Changing or retiring the View changes the connection at once, and a write scope for it is refused with view_bounded_read_only.
  8. credential.8 A client’s access cannot be passed on. Enforced: a client is a project viewer, and creating a key needs an organization owner or admin, so the cell refuses a client who tries. A connection that a client approves has no secret to copy, and it works only through that client’s own approval. Your job: never give a client’s session token to another tool or agent. penumbra auth token prints the token of the session you hold.
  9. credential.9 A key or an agent can be limited to a View when it is created. Enforced: it must hold read scopes only, or the creation is refused with view_requires_read_only, and nothing is created. Your job: use penumbra keys create or penumbra kits connections create with --view, so the key never reads the whole project.

​
Failure signs

​
Doors

​
HTTP reference

​
Keep going

Project · Approval · View · Brain · Find out where you stand in a project · You do not know what your credential can see · Something outside the View reads as not found · A change returned pending