How credentials work
A credential is a connection to another service, such as Jira, Slack, GitHub or AWS: the address, the account and the token or key Jaah signs in there with. A task that needs to file an issue, post a message, push code or launch a machine does it with a credential it was given. You type the secret once, and Jaah never shows it again.
This page explains the ideas behind credentials. For the steps, see Add a credential, Attach a credential to a project and Replace or delete a credential. For every control on the screen, see Credentials.
Terms
| Term | Meaning |
|---|---|
| Credential | One stored connection: a Name, a Type and the fields that type asks for. |
| Type | The service the credential connects to, for example Jira, GitHub or AWS. It decides which fields the form asks for. |
| Secret | A field Jaah keeps hidden, such as an API token or a Secret access key. |
| Owner | Who the credential belongs to: Personal, Organization or System. |
| Attached project | A project the credential is attached to. Every task on it receives the credential. |
| Model account | Not a credential: the AI account a runner signs in as to reach the AI model. See Credentials and model accounts. |
Who owns a credential
When you add a credential, its Owner decides who may use it:
- Personal — yours. Tasks you start can use it, and so can the projects you attach it to.
- Organization — shared across your organization. Org Owners and Admins can use it, and so can their tasks and the tasks on the projects it's attached to.
- System — for Jaah itself, for example cloud nodes. Tasks never see it, and it can't be attached to a project.
Use Personal for a token tied to your own account, and Organization for one the whole team shares. The form shows Owner only to Org Owners and Admins; a credential anyone else adds is personal. The list shows only the credentials you can see: the ones you added, and the ones shared with you.
How tasks use credentials
A credential reaches a task in one of these ways:
- Through its owner. A task you start can use your personal credentials.
- Through a project. A credential attached to a project is given to every task that starts on that project from then on. Detach it, and tasks on that project stop receiving it.
- As an environment variable. A project can hand its tasks one field of a credential as a variable, so the value is never shown on the project. See Add an environment variable.
- For pushing code. A person's Git Access, on their profile, names the stored credential that tasks started from their account push with. See People.
Tasks find a credential by its Name, so make the name say what it's for. Slashes in a name file it in folders, which the Tree view shows.
What happens to a secret
A secret is written once and never read back on screen. When you open a credential, its secret fields stay empty and say Leave blank to keep the stored value. A filled round mark before a credential's name means a secret is stored; a hollow one means none is stored yet.
A credential has no states of its own beyond that. Its life is short to describe:
- Added, with its secrets.
- Attached to the projects that need it, if any.
- Replaced when a token expires or is revoked: type the new value into the same credential, and everything that uses it picks it up.
- Deleted when it's no longer needed. Deleting removes every secret stored with it and can't be undone.
Never paste a secret into a task's description, a project's commands or its agent instructions: anyone who can view those can read it.
Credentials and model accounts
A credential and a model account both hold something secret, but they do different jobs:
| Credential | Model account | |
|---|---|---|
| What it's for | The services a task's work touches: Jira, Slack, GitHub, AWS. | The AI model itself: the account a runner signs in as to think and write. |
| Where it lives | Directory, then Credentials. | Directory, then Model Accounts. |
| How it's chosen | Given to a task by its owner or its project. | Picked for each run from the accounts your organization has. |
| What it shows | Whether a secret is stored. | Its quota, its sessions and the nodes it's signed in on. |
A model account is a Subscription (OAuth) that a person signs in to on a node, or an API key Jaah stores and never shows again. A run uses a subscription's quota, or is billed per token on an API key. See How model accounts work and Model accounts.
Related
- How tasks work — the work a credential is given to.
- How projects work — where credentials are attached.
- How nodes work — the machines runners, and their model accounts, run on.
- How team and access work — the roles that decide who may add, attach and change credentials.