OAuth for apps

​

Endpoints

​

Scopes

​

Connect an app

https://app.usertick.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-app.example.com/oauth/callback
  &response_type=code
  &scope=surveys:read responses:read responses:write webhooks:write
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_THE_VERIFIER
  &code_challenge_method=S256

curl -X POST "https://app.usertick.com/api/oauth/token" \
  -d grant_type=authorization_code \
  -d code=THE_CODE \
  -d redirect_uri=https://your-app.example.com/oauth/callback \
  -d code_verifier=THE_VERIFIER \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

{
  "access_token": "uto_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "utr_...",
  "scope": "surveys:read responses:read responses:write webhooks:write"
}

​

AI assistants

• Discovery. A request to https://mcp.usertick.com/mcp without a token returns 401 with WWW-Authenticate: Bearer resource_metadata="https://mcp.usertick.com/.well-known/oauth-protected-resource/mcp". That document (RFC 9728) names https://mcp.usertick.com/mcp as the resource and https://app.usertick.com as the authorization server, whose metadata lists the endpoints above.
• Client identity. An assistant uses an https URL that serves its Client ID Metadata Document as its client_id (client_id_metadata_document_supported is true), or registers at the registration endpoint. Either way it is a public client: no secret, token_endpoint_auth_method none. A registration takes 1 to 10 redirect URIs: https URLs, http URLs on localhost or 127.0.0.1 (matched on any port), or an app’s own scheme. A registration that nobody approves within a day is deleted.
• PKCE is required. An assistant’s authorization without an S256 code challenge returns 400 with OAU-002-010.
• The resource is the MCP server. An assistant sends resource=https://mcp.usertick.com/mcp on the authorization and the token request (RFC 8707). Any other value returns 400, OAU-002-009 on the consent page and invalid_target at the token endpoint. Its tokens work only through the MCP server; the REST API refuses them with 401 and APK-004-007.
• Who may connect one. Any member may connect an assistant, with no permission needed, and picks the scopes on the consent page. The assistant then works with that member’s own role. A member whose role reaches only some surveys can’t connect one in that organization (403, OAU-002-011), because the assistant reads every survey.
• The plan. The organization must be on the Pro plan or above. On a lower plan, Usertick refuses the approval with 403 and code OAU-002-012.
• Unrecognized assistants. The consent page names an assistant Usertick doesn’t recognize with the name it gave itself, marks it as unrecognized and says where the person goes after answering.

​

Refresh tokens

• An access token lasts 1 hour.
• A refresh token lasts 90 days from when it was issued. Every refresh issues a new one, so a connection that keeps refreshing doesn’t expire.
• Every refresh returns a new access token and a new refresh token, so the app has to store the new refresh token each time.
• A used refresh token presented again within 30 seconds gets its own new pair, so two parallel refreshes don’t break the connection. After those 30 seconds, a reused refresh token revokes every token issued in its chain, and the person has to approve the app again. The connection itself remains, so the webhook subscriptions the app made keep working.
• Usertick stores only hashes of codes and tokens.

curl -X POST "https://app.usertick.com/api/oauth/token" \
  -d grant_type=refresh_token \
  -d refresh_token=utr_... \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

​

Revoke a token

curl -X POST "https://app.usertick.com/api/oauth/revoke" \
  -d token=utr_... \
  -d token_type_hint=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

​

When a connection stops

• a member whose role has the Manage integrations or Manage developer settings permission selects Revoke access on its line under Connections in Settings → Integrations → Zapier, or for an assistant under Settings → Developers → API keys,
• the person who connected it selects Revoke access under Settings → Security,
• the person who connected it leaves the organization or has their account deactivated or scheduled for deletion; for an app such as Zapier also when they lose the Manage integrations permission, and for an assistant when their role stops reaching every survey,
• the organization becomes inactive.

​

Token endpoint errors