Auth Config

Purpose

Use this SOP when a GETQUICK repository needs Ploi API access for a specific site, deployment workflow, or automation.

The goal is to create a Ploi API token with the right scopes, store it safely as a GitHub repository secret, and verify that repository automation can call the Ploi API without exposing credentials.

Context

Ploi API tokens are created from the Ploi account profile. The current official documentation is at:

https://developers.ploi.io/

Ploi documents bearer-token authentication at /getting-started/authorization, scope configuration at /getting-started/scopes, required request headers at /getting-started/headers, and CLI authentication at /cli/getting-started/authenticating.

Ploi API keys are commonly installed in GitHub repositories as encrypted repository secrets for the specific site being built. The token should be named clearly so the Ploi account owner can recognize where it is used and delete it later.

Outcome

After this procedure is complete:

• A dedicated Ploi API token exists for the target GitHub repository or site.
• The token has enough scopes to create and manage the required Ploi resources.
• The token is stored in GitHub Secrets, not committed to the repository.
• The repository has enough non-secret configuration to identify the target Ploi server and site.
• A smoke test proves the token can authenticate against the Ploi API.

Steps

Identify the repository and site

Before creating a token, confirm:

• GitHub repository owner and name.
• Ploi account that owns the target resources.
• Ploi server ID, if the repository targets an existing server.
• Ploi site ID, if the repository targets an existing site.
• Whether automation needs to create new servers, create sites, update environment variables, trigger deployments, manage repositories, or manage certificates.

Use one API key per repository or site whenever possible. Avoid one shared global token across unrelated repositories.

Create the Ploi API key

1. Log in to Ploi.

2. Open the account profile.

3. Go to the API keys page:

   https://ploi.io/profile/api-keys

4. Create a new API token.

5. Name the token after the repository and environment, for example:

   github:getquick/example-site:production

6. Select scopes for the automation the repository needs.

7. Create the token.

8. Copy the token once and store it immediately in GitHub Secrets.

Do not paste the token into chat, commit it to source control, or add it to .env files that are tracked by Git.

Choose scopes

Ploi’s API uses endpoint-specific scopes. The safest default is to grant only the scopes required for the repository workflow.

For a repository that must create and manage everything for a site, include scopes for the relevant resource groups:

• Servers: list, get, create, update, restart, logs, monitoring, services, PHP, SSH keys, databases, database users, crontabs, daemons, network rules, system users, and related server operations used by the workflow.
• Sites: list, get, create, update, suspend, resume, NGINX configuration, clone, PHP version changes, permissions reset, aliases, certificates, redirects, queue workers, environment, repository, deployments, monitoring, apps, and related site operations used by the workflow.
• Deployments: trigger and inspect deployments for the target site.
• Projects or scripts: include these only if the repository automation uses them.

Deletion scopes are special. Add site deletion or server deletion only when the repository explicitly needs teardown automation and the user has approved that risk. For normal production site automation, leave destructive delete scopes disabled.

If the goal is a broad bootstrap token for a new site build, select all create, read, update, deployment, repository, environment, certificate, and database scopes needed for that build, but still avoid delete scopes unless teardown is part of the task.

Add the token to GitHub

1. Open the target GitHub repository.

2. Go to Settings.

3. Go to Secrets and variables.

4. Choose Actions.

5. Add a new repository secret:

   PLOI_API_TOKEN

6. Paste the Ploi token as the value.

7. Save the secret.

If the repository has separate staging and production workflows, use environment-specific secrets instead:

PLOI_API_TOKEN_STAGING
PLOI_API_TOKEN_PRODUCTION

Add non-secret repository configuration

Store stable IDs as GitHub variables or repository configuration, not as secrets unless they reveal sensitive internal structure.

Recommended GitHub Actions variables:

PLOI_SERVER_ID
PLOI_SITE_ID
PLOI_USER_AGENT

Use a clear User-Agent value because Ploi requires API requests to include one:

getquick-example-site-github-actions

Use the token in GitHub Actions

Use the token only through GitHub’s secret context.

Example smoke-test step:

- name: Verify Ploi API auth
  run: |
    curl -fsS https://ploi.io/api/servers \
      -H "Authorization: Bearer $PLOI_API_TOKEN" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "User-Agent: ${PLOI_USER_AGENT:-github-actions}"
  env:
    PLOI_API_TOKEN: ${{ secrets.PLOI_API_TOKEN }}
    PLOI_USER_AGENT: ${{ vars.PLOI_USER_AGENT }}

Example deploy trigger shape:

- name: Trigger Ploi deployment
  run: |
    curl -fsS -X POST "https://ploi.io/api/servers/$PLOI_SERVER_ID/sites/$PLOI_SITE_ID/deploy" \
      -H "Authorization: Bearer $PLOI_API_TOKEN" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "User-Agent: ${PLOI_USER_AGENT:-github-actions}"
  env:
    PLOI_API_TOKEN: ${{ secrets.PLOI_API_TOKEN }}
    PLOI_SERVER_ID: ${{ vars.PLOI_SERVER_ID }}
    PLOI_SITE_ID: ${{ vars.PLOI_SITE_ID }}
    PLOI_USER_AGENT: ${{ vars.PLOI_USER_AGENT }}

Before using an endpoint path, confirm the current path and required scopes in https://developers.ploi.io/.

Rotate or remove access

Rotate the token when:

• A repository changes ownership.
• A contractor or automation no longer needs access.
• The token may have been exposed.
• The repository changes from staging to production usage.
• The token was created with broader scopes than needed.

Remove the token from both Ploi and GitHub when the repository no longer needs Ploi automation.

Validation

Validate the setup from GitHub Actions:

• The workflow can read PLOI_API_TOKEN.
• The smoke test returns a successful response from https://ploi.io/api/servers.
• Requests include Authorization, Accept, Content-Type, and User-Agent headers.
• The workflow can access PLOI_SERVER_ID and PLOI_SITE_ID when required.
• The token is not printed in logs.
• The token is not present in repository files.

Validate locally only if the token is loaded from a secure local secret manager or untracked environment file:

curl -fsS https://ploi.io/api/servers \
  -H "Authorization: Bearer $PLOI_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Agent: getquick-local-smoke-test"

Operational notes for agents

Always check https://developers.ploi.io/ before generating GitHub Actions code for Ploi. Do not invent endpoint paths, request bodies, scopes, or rate limits from memory.

When a user asks for “proper permissions to create and manage everything”, interpret that as all required create, read, update, deployment, repository, environment, certificate, database, and server-management scopes for the target workflow. Do not add destructive delete scopes unless the user explicitly asks for teardown automation.

Never ask a user to paste a Ploi API token into chat. Ask them to add it to GitHub Secrets or to use a secure secret manager.

Important search terms: Ploi API token, Ploi API key, Ploi scopes, GitHub Secrets, GitHub Actions, Ploi deployments, Ploi server ID, Ploi site ID.

Troubleshooting

• If the API returns 401, confirm the GitHub secret value is the Ploi token and that the Authorization: Bearer header is present.
• If the API returns 403, revisit the token scopes in Ploi and add the endpoint-specific permission.
• If the workflow cannot find the token, confirm the secret name matches the workflow exactly.
• If the workflow cannot find the server or site, confirm PLOI_SERVER_ID and PLOI_SITE_ID.
• If requests fail unexpectedly, confirm Accept, Content-Type, and User-Agent headers are present.
• If the token appears in logs, rotate it immediately in Ploi and replace the GitHub secret.