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

# GitHub App

> Create a read-only GitHub App so Expira can list and track the expiry of every fine-grained personal access token in your GitHub organisation.

With a GitHub App installed in your organisation, Expira lists every **fine-grained personal access token** that has access to the organisation, and tracks when each one expires. Tokens are added, updated and removed as people create, rotate and revoke them.

You create the app in your own organisation, so it only ever has the one permission you give it.

## Create the app

**1. Start a new GitHub App**

In GitHub, open your organisation's **Settings → Developer settings → GitHub Apps → New GitHub App**.

**2. Fill in the basics**

* **GitHub App name:** anything, for example "Expira token tracker".
* **Homepage URL:** `https://expira.dev`.
* **Webhook:** clear **Active**. Expira doesn't use webhooks.

**3. Give it one permission**

Under **Permissions → Organization permissions**, set **Personal access tokens** to **Read-only**. Leave every other permission at **No access**.

**4. Limit where it can be installed**

Under **Where can this GitHub App be installed?**, choose **Only on this account**. Then press **Create GitHub App**.

**5. Note the App ID and create a private key**

On the app's **General** page, copy the **App ID**. Further down, press **Generate a private key**. GitHub downloads a `.pem` file.

**6. Install the app in your organisation**

Open **Install App** in the app's sidebar and install it on your organisation. After installing, the browser shows a URL ending in `/installations/12345678`. That last number is the **Installation ID**.

You can find it again later under the organisation's **Settings → GitHub Apps → Configure**, at the end of the page's URL.

## Add the connection in Expira

Go to **Integrations → GitHub Apps → Add App** and fill in:

* **Display name**, for example "Acme GitHub App".
* **GitHub URL:** `https://github.com`, or your GitHub Enterprise Server address.
* **App ID** and **Installation ID** from the steps above.
* **Private key (PEM):** paste the whole contents of the `.pem` file. Both `BEGIN RSA PRIVATE KEY` and `BEGIN PRIVATE KEY` formats work.
* **Organisations to scan:** the organisation's login name, as in `github.com/acme`.

Save, then press **Sync**. Daily syncs run at 08:45 UTC.

> [!TIP]
>
> An installation belongs to one organisation. To scan several organisations, install the app in each one and add one connection per organisation, each with its own Installation ID.

## What Expira sees

Expira calls `GET /orgs/{org}/personal-access-tokens` and reads each token's name, owner and expiry date. It never sees token values.

If the organisation returns "not found" or "forbidden", the app isn't installed there or is missing the **Personal access tokens** permission. If nothing at all could be read, the sync reports an error.

## Rotate the private key

Generate a new private key on the app's **General** page, paste it into the connection's **Edit** form, then delete the old key in GitHub.


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