Search docs
Docs searchUpload Connection
API Tokens & Upload Connection
Use organization-scoped API tokens to connect local ArchPilot validation to ArchPilot Cloud governance upload safely and consistently.
API tokens connect local ArchPilot validation workflows to the shared Cloud workspace.
Plan availability
Token behavior is organization-scoped. Use organization API tokens for manual upload on all plans and for automated CI upload on paid plans.
Manual upload tokens
Use an organization API token for explicit local or Inspector-driven governance upload.
CI automation tokens
Use the same token model for automatic main-branch CI upload when the organization is on a paid plan.
Organization token limits
Token limits are organization-scoped: Free includes 1 token, Team up to 5, Growth up to 20, and Enterprise uses a custom allocation.
Separate user sign-in from repository upload
People sign in to the ArchPilot Cloud workspace with their user account. Automation uploads governance snapshots with an organization API token.
An organization API token identifies which organization should receive the uploaded snapshot. The upload tenant comes from the token, not from a human login session and not from payload organization fields.
Where to create and manage tokens
API tokens support manual uploads on all plans. Automated CI uploads require a paid plan.
API token count varies by plan.
That is why you should copy the token immediately and place it into your local ArchPilot connection or CI configuration before leaving the page.
- Create tokens in ArchPilot Cloud at Settings, Tokens.
- Only organization admins can create or revoke tokens.
- The full token value is shown once after creation.
- After that, Cloud stores only a safe prefix in the UI and the token hash for verification.
Manual upload and CI upload are separate
Manual governance upload is available on all plans. Teams can validate locally or in CI and run an explicit upload when they want to publish a snapshot to ArchPilot Cloud.
Automatic CI upload on pushes to main is available on paid plans.
ArchPilot Cloud treats each upload as either manual or CI so plan enforcement stays clear and predictable.
- Manual upload: available on all plans
- Automatic CI upload on main: available on paid plans
- Validation in CI: available on all plans
Use the ArchPilot Cloud URL
Use this URL in the CLI, extension, or GitHub Actions configuration.
Use the same value everywhere so local setup and CI match.
- Use your organization API token from ArchPilot Cloud as the upload token.
Use the ArchPilot Cloud URL:
https://api.archpilot.orgStore the token in local config or CI
Use the token in one of two places: the repository's saved Cloud connection or your CI configuration.
A saved connection is helpful for local repeated uploads. CI configuration is the right place for branch automation.
Validation must run before upload so ArchPilot can generate the required artifacts.
Example saved connection
{
"cloud": {
"server": "https://api.archpilot.org",
"token": "ap_live_1234567890_example",
"uploadOnValidate": true
}
}Common mistakes
- Using the wrong token. Use your organization API token from ArchPilot Cloud.
- Expecting archpilot validate to upload automatically.
- Trying to upload before validation artifacts exist.
- Using an expired or revoked token.
- Using the wrong ArchPilot Cloud URL.
Why this matters
This model keeps governance upload explicit and organization-scoped, which gives teams clear control over which organization receives each snapshot.
It also keeps user sign-in and upload credentials separate, which is safer for people and clearer for automation.
When to use uploadOnValidate
A saved Cloud connection can include an upload-on-validate preference. Treat that setting as an explicit opt-in convenience for local workflows.
If your team wants clearer control, keep upload explicit and run governance upload as its own command after validation.