Skip to content
Pillion
Join the waitlist
Explore Pillion

Pillion docs

Authentication and API

Learn how browser sign-in, access tokens and SSH keys connect you to Pillion, then explore the API when you are ready to automate tasks.

Choose how you want to connect

Authentication means proving who you are. Pillion needs that proof when you read a private repository or change something. How you provide it depends on the tool you are using:

  • In your browser: sign in with an email code, sign-in link or passkey.
  • From Git over HTTPS: use your username and a personal access token. This is the route used in Your first repository.
  • From Git over SSH: use a key pair saved on your computer and registered with Pillion. This is an alternative if you already use SSH.
  • From a script or integration: use a token to call the API, explained in the reference section below.

Being signed in does not automatically give you access to every repository. Its owner must also grant you an appropriate repository role.

Browser sign-in

On Sign in, enter your email and use the code or link sent to it. A magic link is a sign-in link from that email. A passkey lets you sign in using your device or password manager’s authentication.

Add passkeys in Settings → Passkeys. A session is a browser sign-in Pillion remembers; review or revoke sessions in Settings → Sessions, for example after using a shared computer.

Git and API clients use their own credentials. An emailed sign-in code is not a Git password.

Create a personal access token

A personal access token, sometimes called a PAT, is a secret string a tool uses to act as you. “Fine-grained” means you choose which owner, repositories and operations it can access. You can revoke one token without signing out every other tool.

  1. Open Settings → Access tokens.
  2. Select the owner: your user account or an organization.
  3. Select the permissions needed by the client. Use Contents: read for clone and fetch, or Contents: write for push. Updating workflow files also needs Workflows: write.
  4. Turn on Limit to selected repositories and select the repositories this tool needs. Leave the limit off only when you intend it to cover repositories across that owner.
  5. Select Generate new token and copy the value immediately. It is shown only once.

A token belongs to one user and one owner. It cannot grant more access than the user already has, and its repository allow-list still applies. Use separate tokens for clients with different needs. Revoke a lost or unused token in the same settings page.

For HTTPS Git, use your username and supply the token when prompted for a password. Save it through your Git credential manager; do not put it in a remote URL or commit it in a file.

SSH keys

SSH uses two related keys: a private key that stays on your machine and a public key that you register with a service. Git proves it has the private key when connecting. An SSH public-key file usually has a .pub extension.

Add your public SSH key in Settings → SSH keys, then copy the SSH URL from the repository’s clone menu. Only upload the public key; keep its private key on your machine.

git clone git@pillion.dev:OWNER/REPOSITORY.git

Use the host and path from your repository’s clone URL. A deploy key, configured in repository Settings → Deploy keys, belongs to one repository rather than a user. Git LFS still uses HTTPS and needs an HTTPS credential for private data.

Troubleshoot access errors

  • 401: check that the token is present, valid and has not been revoked.
  • 403: check the token’s permission level, your repository role, SSO authorization and applicable rulesets.
  • 404: check the owner and repository name, token owner and repository allow-list. Private resources can return 404 when you cannot read them.

Reference: automate tasks with the REST API

An API lets a program read or change information on Pillion through requests, such as listing a repository’s issues. You can use the website and Git without learning the API. This section is for writing scripts or connecting an integration.

The API uses GitHub-shaped REST routes at /api/v1; /api/v3 is an alias for clients that expect it. In a shell where PILLION_TOKEN already contains your access token, this example reads a repository’s metadata:

curl --fail-with-body \
  -H "Authorization: Bearer $PILLION_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  'https://pillion.dev/api/v1/repos/OWNER/REPOSITORY'

Replace the host, owner and repository with yours. Request only the permissions the integration needs. List endpoints use pagination; use page and per_page where supported rather than assuming a response contains every result.

GitHub compatibility has boundaries: GraphQL and the search API are not implemented. An integration that depends on them needs to use supported REST endpoints instead.

Reference: GitHub CLI compatibility

Authenticate gh with a personal access token and your Pillion hostname. Use the token flow rather than browser OAuth:

printf '%s' "$PILLION_TOKEN" | gh auth login --hostname pillion.dev --with-token
gh api --hostname pillion.dev repos/OWNER/REPOSITORY

REST-based commands can use the API alias. Commands that depend on GraphQL are not supported, so not every gh command works.

Need a hand? Contact us or check the service status.