fluentcidocs
Website GitHub

Studio and publishing

Cache access

Generate cache upload tokens, invite collaborators, and authorize CI with revocable credentials.

For client-specific token examples, see remote build cache.

Generate an upload token

Open Build cache and sign in with your AT Protocol account. Older sessions show Authorize cache access; approve the additional cache permissions before continuing.

Choose Generate upload token to receive your account's cache URL and an upload token valid for one hour. Keep the owner field empty for your own cache. For a shared cache, enter the owner's handle or DID after they invite you. The browser obtains a short-lived PDS service-auth JWT bound to the exact cache API method, then exchanges it at the FluentCI API. PDS session credentials are not sent to the FluentCI API. Upload tokens remain in page memory and disappear on sign-out, reload, or expiry.

Configure your cache client with the returned URL and a bearer token or a Basic-auth password. For the Go helper:

export FLUENTCI_CACHE_URL='https://cache.example/accounts/OWNER_HASH'
export FLUENTCI_CACHE_TOKEN='UPLOAD_TOKEN'
export GOCACHEPROG='fluentci-cache gocache'
go build ./...

Use Renew upload token for a new one-hour token. Renewing does not revoke a previous token. Cached files remain publicly readable through a correctly configured CDN; invitations and tokens control uploads.

Invite a collaborator

In Invite collaborators, enter a handle or DID and choose Invite user. This grants upload access to your own cache. Share your handle with the user; they sign in and generate their own upload token with you as the cache owner. No email or external invitation message is sent automatically.

Revoke access immediately prevents that user from generating more tokens. Already-issued upload tokens remain valid until their one-hour expiry.

Connect CI

In CI credentials, name and create a credential for your own cache. Copy its secret immediately: it is shown once and cannot be recovered from the API. The server stores only a SHA-256 hash. Save the secret as FLUENTCI_CACHE_CREDENTIAL in your CI secret store, never in source control. Credentials expire after 90 days and can be revoked in the same page. Create a replacement and update the CI secret before revoking the old credential.

Each CI run exchanges this credential for a fresh one-hour upload token. CI does not need an AT Protocol account password, OAuth session, or browser login. For jobs longer than one hour, repeat the exchange immediately before uploading. Revoking a CI credential blocks new exchanges; existing upload tokens expire normally. A CI credential only authorizes the token exchange endpoint, with no permission to manage collaborators, other credentials, or cache administration.

From a checkout of this repository, use the Node.js 22+ helper:

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Get cache upload token
        env:
          FLUENTCI_CACHE_CREDENTIAL: ${{ secrets.FLUENTCI_CACHE_CREDENTIAL }}
        run: node scripts/cache-token.mjs --github-env
      - name: Build
        run: |
          # FLUENTCI_CACHE_URL and FLUENTCI_CACHE_TOKEN are available here.
          # Configure your cache client, then run your build.
          go build ./...

The helper masks the upload token and writes the variables to GITHUB_ENV. It requires no GitHub OIDC permissions. The Go example also needs Go and the fluentci-cache helper installed and GOCACHEPROG set as shown above. For other repositories, vendor the helper or use the HTTP exchange directly. For other CI providers, write a private environment file:

node scripts/cache-token.mjs --env-file .cache-upload.env
set -a
. ./.cache-upload.env
set +a
# Run the cache client, then delete the environment file when done.

Keep that file out of source control and build artifacts. The helper writes it with owner-only permissions and does not print its contents.

API methods

All methods are JSON POST requests under https://api.fluentci.io/xrpc/io.fluentci.cache..

Method Authentication Input
createToken Method-bound PDS service JWT {} or { "owner": "handle.example" }
inviteUser Owner's method-bound PDS service JWT { "actor": "handle.example" }
revokeUser Owner's method-bound PDS service JWT { "actor": "handle.example" }
createCredential Owner's method-bound PDS service JWT { "label": "Release pipeline" }
listCredentials Owner's method-bound PDS service JWT {}
revokeCredential Owner's method-bound PDS service JWT { "id": "CREDENTIAL_UUID" }
exchangeCredential CI credential in the bearer header {}

createToken and exchangeCredential return token, expiresAt, cacheUrl, and owner. Secret-bearing responses use Cache-Control: no-store. Credential lists return metadata only, with up to the latest 100 entries. A user may create CI credentials for their own cache; an invitation alone does not grant management of the owner's CI credentials.

Explore storage and manage collaborators

On the cache page, enter a collaborator's handle to see account suggestions. Select an account with the mouse or arrow keys and Enter, then invite them. Use Refresh collaborators to list users with upload access and Remove to revoke a grant. Existing upload tokens still expire within one hour.

Under Cache storage, choose Explore keys to view keys, byte sizes and modification dates. Filter by a key prefix and use More keys for further pages. Total bytes and key count cover your entire account cache. They are computed from object metadata, so large caches take longer and concurrent uploads can change the totals.

Only owners can manage storage. Delete individual objects after confirmation, or use Clear cache and type CLEAR to remove all objects in your own cache. Other accounts and legacy shared storage are unaffected. Invited users and CI upload credentials cannot list or delete storage. Deletions are permanent at the origin; public CDN copies may remain until their cached responses expire. Pause uploads when clearing a cache if you need it to remain empty.

The owner-only JSON procedures are io.fluentci.cache.listKeys (optional prefix, cursor, limit up to 200), io.fluentci.cache.deleteKey (key), io.fluentci.cache.clearCache (confirm: true) and io.fluentci.cache.listCollaborators (optional cursor). Each requires its own method-scoped service-auth JWT. Storage management needs S3 list and delete permissions in addition to upload permissions.

Made with ♥ in Antananarivo, Madagascar.
Search documentation