OAuth integrations

Connect partner and platform applications with OAuth 2.0.

Choose an authentication method

Personal API keyA private integration acting as one PackCloud user.

Authorization CodeA partner or platform application connecting PackCloud users.

Public or machine clientA client provisioned together with PackCloud.

Client Credentials is not a self-service GraphQL flow. Contact PackCloud before building a machine integration around it.

Register a confidential client

Open auth.pack.cloud/profile and find OAuth Clients.
Select Create OAuth Client.
Enter a client name and at least one redirect URI.
Copy the client ID and secret. The secret is shown only once.

Redirect URIs must be distinct absolute http:// or https:// URLs and are normally matched exactly. Wildcards are not supported. You can edit redirect URIs or delete the client from the same profile section.

1. Redirect the user for authorization

GET https://auth.pack.cloud/oauth/authorize

response_type=code
client_id=<client-id>
redirect_uri=https://example.com/oauth/callback
state=<unguessable-state>
code_challenge=<pkce-challenge>
code_challenge_method=S256

Generate and verify state for every authorization request. PKCE is required for public clients and recommended for confidential clients. Use S256; the corresponding verifier must contain 43–128 RFC 7636 characters.

After the user approves access, PackCloud redirects to the registered URI with a single-use authorization code. Codes expire after 10 minutes.

2. Exchange the authorization code

Send form-encoded data from your backend. Never expose a confidential client secret in browser code.

POST https://auth.pack.cloud/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
client_id=<client-id>
client_secret=<client-secret>
code=<authorization-code>
redirect_uri=https://example.com/oauth/callback
code_verifier=<pkce-verifier>

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "...",
  "refresh_token": "..."
}

Use the returned access token as Authorization: Bearer <access-token> when calling GraphQL. Access still follows the authorizing user's current memberships and rights.

3. Refresh access

Access tokens expire after one hour. Exchange the refresh token at the regular token endpoint.

POST https://auth.pack.cloud/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=<refresh-token>
client_id=<client-id>
client_secret=<client-secret>

The response contains a new access token and refresh token. Refresh tokens expire after 30 days and rotate when used, so replace the stored value after every successful refresh.

Do not use /oauth/token/refresh. That is an internal browser-session helper, not the OAuth refresh-token endpoint.

Revoke the current token

POST https://auth.pack.cloud/oauth/token/revoke
Authorization: Bearer <current-access-token>

A successful request returns 204 No Content and revokes the current access token and its attached refresh tokens. This PackCloud endpoint does not accept an arbitrary token parameter.

Scopes and client types

PackCloud currently defines no OAuth scopes for GraphQL. Omit scope or leave it empty; non-empty unknown scopes fail with invalid_scope. GraphQL authorization comes from the user's organization and warehouse access, not OAuth scope names.

The profile creates confidential Authorization Code clients with refresh tokens. Public clients such as browser or mobile apps, and Client Credentials clients for machine-to-machine use, require provisioning by PackCloud.