Guild supports the OAuth 2.0 authorization code flow for external applications that need a Guild user to sign in, grant access, and call Guild APIs.
Use this guide when you are building a third-party integration that connects to Guild. The OAuth flow issues bearer access tokens, supports refresh tokens, and supports PKCE for public clients.
Access tokens last 1 day and are sent with Authorization: Bearer ACCESS_TOKEN.
Refresh tokens last 30 days and rotate when used.
Authorization codes expire after 10 minutes and can only be used once.
Create an OAuth app
Create OAuth credentials from an OAuth settings page while signed in to Guild. The client secret is only shown once, so store it securely when the app is created.
1
Open OAuth settings
For a user app, open /USER_SLUG/settings/oauth. For a Guild app, open /GUILD_SLUG/settings/oauth as a Guild organizer. For an Event app, open /events/EVENT_SLUG/settings/oauth as someone who can manage the Event.
2
Register redirect URIs
Add every callback URL your integration will use. HTTPS URLs are accepted for production, loopback HTTP URLs are accepted for local development, and custom app schemes are accepted for native apps.
3
Copy the credentials
Copy the client ID and client secret immediately. Existing OAuth apps show the client ID later, but not the secret.
Redirect URI rules
Production callbacks should use https://.
Local development can use loopback http://localhost, http://127.x.x.x, or IPv6 loopback URLs.
Native apps can use custom schemes such as myapp://oauth/callback.
Redirect URIs cannot include URL fragments and cannot use unsafe schemes such as javascript:, data:, file:, or blob:.
Send the user to Guild
Start the authorization flow by sending the user to Guild withresponse_type=code, your client_id, a registered redirect_uri, requested scopes, and a random state value.
Public clients should use PKCE with code_challenge_method=S256.
Supported scopes
profile:read allows access to the authenticated user's basic profile through the userinfo endpoint.
event_tickets:read allows access to the authenticated user's Event ticket status.
event_attendees:read allows access to Event attendee data when the authorized Guild user can manage the requested Event.
Handle the callback
After the user allows access, Guild redirects to the registered callback URL with code and state. Validate that the returned state matches the value your app originally sent.
If the user denies access, Guild redirects with error=access_denied.
Exchange the code for tokens
Exchange the authorization code at the token endpoint. The endpoint accepts form-encoded requests and JSON requests, but form-encoded is recommended for OAuth clients.
Public clients using PKCE send the original code_verifier. Confidential clients can also use PKCE, but should still authenticate with the client secret when they can keep it private.
Refresh tokens
Use grant_type=refresh_token to get a new access token. Refresh tokens rotate, so replace the stored refresh token with the new one returned by the response.
Call Guild APIs
User profile
Use the userinfo endpoint with a bearer access token.
Event ticket check
To determine whether the signed-in Guild user has a ticket for an Event, call the Event ticket endpoint with event_tickets:read.
Event attendees
The Event attendees API requires event_attendees:read, and the authorized Guild user must be able to manage the Event.
Local development
For local testing, create an OAuth app from your local OAuth settings page and register a loopback redirect URI. Keep local credentials generic in docs and examples, and do not reuse them in production.