OAuth 2.0 for Rocks

OAuth 2.0 for Rocks

PetRock.cloud supports OAuth 2.0 for third-party applications that need to access user workspaces and rocks on behalf of users. This article documents the Authorization Code flow with PKCE, supported scopes, and token management.

When to use OAuth

Use OAuth when:

• You are building an application that other PetRock.cloud customers will install
• You need long-lived access on behalf of a user without storing their credentials
• You require fine-grained scope control

For first-party integrations within your own workspace, use API tokens instead. See Setting Up Sandbox and Production Environments.

Registering an OAuth application

1. Navigate to Developer → OAuth Applications.
2. Click New Application.
3. Enter:
   • Application name (visible to users on the consent screen)
   • Redirect URIs (one or more, must be HTTPS in production)
   • Application logo (optional, 256x256 PNG recommended)
4. Click Create.

You will receive a client_id and client_secret. Store the secret in a secure location; it cannot be retrieved later.

Available scopes

Request the minimum set of scopes your integration requires.

Authorization Code flow with PKCE

Step 1: Generate PKCE code verifier and challenge

const verifier = base64UrlEncode(crypto.randomBytes(32));
const challenge = base64UrlEncode(
  crypto.createHash('sha256').update(verifier).digest()
);

Step 2: Redirect the user to the authorization endpoint

https://auth.petrock.cloud/oauth/authorize
  ?response_type=code
  &client_id=<your_client_id>
  &redirect_uri=<your_redirect_uri>
  &scope=rocks:read+webhooks:write
  &state=<random_state>
  &code_challenge=<challenge>
  &code_challenge_method=S256

The user will see a consent screen listing the scopes you requested.

Step 3: Exchange the authorization code for tokens

After the user approves, they are redirected to your redirect_uri with a code query parameter.

curl -X POST https://auth.petrock.cloud/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<the_code>" \
  -d "redirect_uri=<your_redirect_uri>" \
  -d "client_id=<your_client_id>" \
  -d "code_verifier=<verifier>"

Response:

{
  "access_token": "ptr_at_...",
  "refresh_token": "ptr_rt_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "rocks:read webhooks:write"
}

Step 4: Use the access token

curl https://api.petrock.cloud/v1/rocks \
  -H "Authorization: Bearer ptr_at_..."

Refreshing tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new one:

curl -X POST https://auth.petrock.cloud/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=ptr_rt_..." \
  -d "client_id=<your_client_id>"

Refresh tokens rotate on every use. Always store the new refresh token returned in the response.

Revocation

Users can revoke your application's access from Settings → Connected Applications. You can also revoke programmatically:

curl -X POST https://auth.petrock.cloud/oauth/revoke \
  -d "token=<token_to_revoke>" \
  -d "client_id=<your_client_id>" \
  -d "client_secret=<your_client_secret>"

Warning: Revocation is immediate. In-flight requests using the revoked token will return 401 Unauthorized.

Related articles

• Webhook Setup
• Zapier Integration
• Setting Up Two-Factor Authentication