Authentication

Drok supports three authentication methods for API access: personal access tokens for user-level access, OAuth 2.0 apps for third-party integrations, and bot accounts for automated workflows.

Personal Access Tokens

Tokens are the primary method for API authentication. They are scoped, expirable, and auditable.

Creating Tokens

drok token create --name "ci-deploy" --scopes repo:read,package:write --expiry 90d

Or through the web interface: User Settings > Access Tokens > Create Token.

Token Scopes

Token Properties

• Expiration — Tokens can be set to expire after a specified duration (1 day to 1 year) or never expire. Expiring tokens are recommended for security.
• Repository scoping — Tokens can be limited to specific repositories.
• IP restriction — Enterprise tokens can be restricted to specific IP ranges.

Using Tokens

Include the token in the Authorization header:

curl https://drok.us/api/v1/user \
  -H "Authorization: Bearer drok_pat_xxxxxxxxxxxx"

Revoking Tokens

drok token revoke drok_pat_xxxxxxxxxxxx

Revocation is immediate. Any in-flight requests authenticated with the revoked token will complete, but subsequent requests will fail.

Listing Tokens

drok token list

The token value is never displayed after creation. Only the token name, scopes, last used timestamp, and expiration are shown.

OAuth 2.0 Applications

For third-party applications that need to act on behalf of users.

Registering an OAuth App

Navigate to User Settings > Developer Settings > OAuth Apps and provide:

• Application name — Displayed to users during authorization
• Redirect URI — Where users are sent after authorization
• Scopes — Maximum scopes the app can request

Authorization Flow

GET https://drok.us/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  scope=repo:read,mr:write&
  state=random_state_string

After user authorization, Drok redirects to your callback with an authorization code:

https://your-app.com/callback?code=AUTH_CODE&state=random_state_string

Exchange the code for an access token:

curl -X POST https://drok.us/oauth/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://your-app.com/callback"

Response:

{
  "access_token": "drok_oauth_xxxxxxxxxxxx",
  "token_type": "bearer",
  "scope": "repo:read,mr:write",
  "expires_in": 28800
}

Refresh Tokens

OAuth tokens expire after 8 hours. Use the refresh token to obtain a new access token:

curl -X POST https://drok.us/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=drok_refresh_xxxxxxxxxxxx" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Bot Accounts

Bot accounts are machine identities for automated workflows. They do not consume a seat in your organization.

drok bot create my-org/deploy-bot --scopes repo:read,pipeline:write

Bot accounts:

• Have their own identity and appear as distinct actors in audit logs
• Are scoped to an organization
• Can be assigned to teams for repository access
• Are managed by organization admins

Token Formats

All Drok tokens use a prefixed format for identification:

This prefix format enables secret scanning — Drok's own scanners and third-party tools can identify Drok tokens in source code and alert on accidental exposure.