> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Credential

> Your credential is a person's session, an API key or an approved agent, and it decides what you can do and see in a project.

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](https://docs.pnbr.io/concepts/approval.md)). The part of a project a View shows (card [View](https://docs.pnbr.io/concepts/view.md)). Choosing the project (card [Project](https://docs.pnbr.io/concepts/project.md)).

## 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](https://docs.pnbr.io/concepts/approval.md)).
* Which project a command runs in: card [Project](https://docs.pnbr.io/concepts/project.md).
* Building the part of the project a client may read: card [View](https://docs.pnbr.io/concepts/view.md).

## 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

* A command exits with code 4 and prints `pending`: problem
  [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md).
* A read is not found, though the person says it exists, and you may be
  limited to a View: problem [hidden-reads-as-missing](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md).
* You cannot tell what you may see: problem [what-can-this-credential-see](https://docs.pnbr.io/troubleshooting/what-can-this-credential-see.md).
* A key is refused as "not active", and it is not revoked: rule [credential.5](https://docs.pnbr.io/concepts/credential.md#rule-credential-5).
* A command says it needs a person's session: rule [credential.4](https://docs.pnbr.io/concepts/credential.md#rule-credential-4).

## Doors

| Door | Call |
| - | - |
| CLI (identity) | `penumbra whoami`, `penumbra status`, `penumbra access me`, `penumbra projects list` |
| CLI (sign in) | `penumbra login`, `penumbra connect`, `penumbra logout`, `penumbra auth token` |
| CLI (keys) | `penumbra keys create`, `penumbra keys list`, `penumbra keys scopes`, `penumbra keys revoke` |
| MCP | none reports your credential's kind, role or View. `penumbra_projects` lists the projects the connection reaches. Use the CLI. |
| SDK | `accessProfile` reads the role and what each command family allows, and `access.me` reads the View. |

## HTTP reference

* [Get caller](https://docs.pnbr.io/api/http-me-get.md)
* [List accessible projects](https://docs.pnbr.io/api/http-me-project-scopes.md)
* [List projects](https://docs.pnbr.io/api/http-projects-list.md)
* [Get project connections](https://docs.pnbr.io/api/http-projects-connections-list.md)
* [Get caller access](https://docs.pnbr.io/api/http-access-me.md)
* [List approvals](https://docs.pnbr.io/api/http-approvals-list.md)
* [Get approval](https://docs.pnbr.io/api/http-approvals-get.md)

## Keep going

[Project](https://docs.pnbr.io/concepts/project.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [View](https://docs.pnbr.io/concepts/view.md) · [Brain](https://docs.pnbr.io/concepts/brain.md) · [Find out where you stand in a project](https://docs.pnbr.io/guides/orient.md) · [You do not know what your credential can see](https://docs.pnbr.io/troubleshooting/what-can-this-credential-see.md) · [Something outside the View reads as not found](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md) · [A change returned pending](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.