Does a Portainer API key expire, and what is the safest way to test integrations without production credentials?

Short answer

Portainer CE access tokens (API keys) historically did not expire by default — they stayed valid until revoked. Some recent 2.x releases added an optional expiration at creation time, but this is version-sensitive, so check your exact release rather than assuming either behavior. An expired or revoked token returns HTTP 401 with a generic JSON error body that does not reliably distinguish "expired" from "revoked" from "malformed." And no, there is no documented fully ephemeral validate-only auth endpoint — the registry "Test connection" button validates credentials, but the registry entry itself is persisted.

Token lifecycle: what is confirmed vs. what to verify

Confirmed behavior across Portainer CE 2.x:

• Tokens are created per user (My account → Access tokens, or POST /api/users/{id}/tokens). The raw value is shown once; only a digest is stored.
• A token inherits the full permissions of its owning user — there is no per-token scope reduction. This is why a dedicated low-privilege test user matters more than token configuration.
• Tokens can be revoked at any time from the same UI screen or via the API, which should be your cleanup step after each test run.

Version-sensitive (verify on your instance): whether the creation dialog offers an expiration field and what the default TTL is. Check your version via GET /api/status or the UI footer, then create a token and see if an expiry option appears. If it does, set the shortest TTL in your test instance so your pipeline actually exercises the expiry path.

Distinguishing credential failure from integration failure

Design your script around a simple rule, because the API won't give you more granularity:

• 401 on a previously working token = token-lifecycle event (expired, revoked, or invalid). Treat all 401s uniformly as credential failures and re-check token state in the UI.
• 403 = the token was accepted but the user lacks RBAC permission for that resource. This is an authorization-scope problem, not an auth problem.
• 2xx with wrong/empty data, or 5xx = genuine integration failure.

Verify the exact shape on your instance:

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "X-API-Key: ptr_xxxx" \
  http://localhost:9000/api/endpoints
# revoke the token in the UI, then repeat and record status + body

If your version supports expiry, set the minimum TTL, wait, and compare the response to the revoked case. Expect them to look identical; if they do, your pipeline should log "credential rejected" rather than a specific cause.

Your isolated test plan

Your plan is sound, with two additions:

1. Create a dedicated non-admin test user and issue the token from that account, since tokens can't be scoped below the user's own permissions.
2. Bind the test Portainer only to its own local Docker socket or a throwaway daemon — never mount a production socket, even in a "test" container.

For the registry: "Test connection" validates dummy credentials without any pull or deployment, and it should fail cleanly with fake values. But the registry entry is stored in Portainer's database, so if "persist nothing" is a hard requirement, delete the registry entry via the API after the test, or destroy the whole data volume — which, since your instance is disposable, is the simplest guarantee.

Uncertainty note

Expiry defaults and the exact error JSON have changed across 2.x releases and are flagged here for verification against your deployed version rather than asserted. The 401/403 split and the per-user token model are stable behavior you can build against.