Personal Access Tokens

Create and manage personal access tokens for API authentication and CI/CD pipeline integration with Outpost.

Personal Access Tokens (PATs) allow you to authenticate with the Outpost API and Git over HTTPS without using your password. They are designed for programmatic access, CI/CD pipelines, and automation workflows where interactive login is not possible.

Creating a Token

Navigate to Settings > Access Tokens in your Outpost dashboard.
Click Generate New Token.
Enter a descriptive name for the token (e.g., "GitHub Actions", "Jenkins CI", "Local CLI").
Select the scopes that define what this token can access:

Scope	Grants access to
`repo`	Read and write access to repositories
`repo:read`	Read-only access to repositories
`machine`	Manage and connect to machines
`service`	Deploy and manage services
`job`	Create and manage jobs
`admin:org`	Manage organization settings and members
`admin:ssh_key`	Manage SSH keys on your account

Optionally, set an expiration date. Tokens can be set to expire in 30, 60, 90 days, or with no expiration.
Click Create Token. Your token is displayed once -- copy it immediately and store it securely.

Outpost does not store your token value after creation. If you lose it, you will need to regenerate a new token. Treat tokens like passwords.

Using Tokens for API Authentication

Include your token in the Authorization header when making requests to the Outpost API:

curl -H "Authorization: Bearer op_pat_xxxxxxxxxxxxxxxxxxxx" 
  https://outpost.run/auth/v1/v1/repos

curl -H "Authorization: Bearer op_pat_xxxxxxxxxxxxxxxxxxxx" 
  https://outpost.run/auth/v1/v1/repos

Or set it as an environment variable to keep it out of your shell history:

export OUTPOST_TOKEN="op_pat_xxxxxxxxxxxxxxxxxxxx"
 
curl -H "Authorization: Bearer $OUTPOST_TOKEN" 
  https://outpost.run/auth/v1/v1/repos

export OUTPOST_TOKEN="op_pat_xxxxxxxxxxxxxxxxxxxx"
 
curl -H "Authorization: Bearer $OUTPOST_TOKEN" 
  https://outpost.run/auth/v1/v1/repos

Using Tokens for Git over HTTPS

When cloning or pushing to repositories over HTTPS, use your token as the password:

git clone https://outpost.run/your-namespace/your-repo.git
# Username: your-username
# Password: op_pat_xxxxxxxxxxxxxxxxxxxx

git clone https://outpost.run/your-namespace/your-repo.git
# Username: your-username
# Password: op_pat_xxxxxxxxxxxxxxxxxxxx

To avoid entering credentials on every operation, configure Git's credential helper:

# Store credentials in memory for 1 hour (3600 seconds)
git config --global credential.helper 'cache --timeout=3600'
 
# Or store permanently in an encrypted keychain (macOS)
git config --global credential.helper osxkeychain

# Store credentials in memory for 1 hour (3600 seconds)
git config --global credential.helper 'cache --timeout=3600'
 
# Or store permanently in an encrypted keychain (macOS)
git config --global credential.helper osxkeychain

For automated environments, you can embed the token directly in the remote URL:

git clone https://your-username:[email protected]/your-namespace/your-repo.git

Only use this approach in secure, ephemeral environments like CI runners.

Using Tokens in CI/CD Pipelines

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy to Outpost
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Deploy service
        env:
          OUTPOST_TOKEN: ${{ secrets.OUTPOST_TOKEN }}
        run: |
          curl -X POST 
            -H "Authorization: Bearer $OUTPOST_TOKEN" 
            -H "Content-Type: application/json" 
            -d '{"branch": "main"}' 
            https://outpost.run/auth/v1/v1/services/your-service/deploy

# .github/workflows/deploy.yml
name: Deploy to Outpost
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Deploy service
        env:
          OUTPOST_TOKEN: ${{ secrets.OUTPOST_TOKEN }}
        run: |
          curl -X POST 
            -H "Authorization: Bearer $OUTPOST_TOKEN" 
            -H "Content-Type: application/json" 
            -d '{"branch": "main"}' 
            https://outpost.run/auth/v1/v1/services/your-service/deploy

GitLab CI

# .gitlab-ci.yml
deploy:
  stage: deploy
  script:
    - |
      curl -X POST 
        -H "Authorization: Bearer $OUTPOST_TOKEN" 
        -H "Content-Type: application/json" 
        -d '{"branch": "main"}' 
        https://outpost.run/auth/v1/v1/services/your-service/deploy
  only:
    - main

# .gitlab-ci.yml
deploy:
  stage: deploy
  script:
    - |
      curl -X POST 
        -H "Authorization: Bearer $OUTPOST_TOKEN" 
        -H "Content-Type: application/json" 
        -d '{"branch": "main"}' 
        https://outpost.run/auth/v1/v1/services/your-service/deploy
  only:
    - main

Always store your token as a secret or protected variable in your CI/CD platform. Never commit tokens to your repository.

Managing Tokens

From Settings > Access Tokens you can:

View all active tokens, including their name, scopes, creation date, and last used date.
Regenerate a token to get a new value while preserving its name and scopes.
Revoke a token to immediately invalidate it. Any request using a revoked token will receive a 401 Unauthorized response.

Security Best Practices

Warning

Follow these guidelines to keep your tokens and account secure.

Principle of least privilege — Grant only the scopes a token needs. A CI pipeline that only reads code should use repo:read, not repo.
Set expiration dates — Use short-lived tokens for CI/CD and rotate them regularly. Reserve non-expiring tokens for long-running infrastructure only.
Never commit tokens — Add .env files and credential files to your .gitignore. Enable secret scanning on your repositories to catch accidental exposure.
Use separate tokens per service — Create dedicated tokens for each CI/CD pipeline, script, or integration. This limits the blast radius if a token is compromised.
Monitor usage — Review the "last used" timestamp on your tokens periodically. Revoke any tokens that are no longer active.
Rotate after compromise — If you suspect a token has been exposed, revoke it immediately and generate a replacement.

Next Steps

SSH Keys -- Set up SSH key authentication for repository access and machine connections.
Teams Overview -- Learn about namespaces, roles, and member management.

Previous → SSH Keys

Next Overview →