Creating an app

Open the Developer portal and go to the OAuth apps tab, then click Create app. Everything on this page is editable afterwards except the client id.

Identity

These fields are what the user sees on the consent screen, so they are the difference between "this looks legitimate" and "cancel".

The portal also collects a short tagline and a support email address that are used on the marketplace listing.

Redirect URIs

A redirect URI is where Circa sends the user back after they approve or deny. This is the security boundary of the whole flow: if an attacker could get Circa to deliver an authorization code to a URL they control, the client secret would be the only thing standing between them and the user's data. So the rules are strict.

• Exact match, never prefix match. The redirect_uri you send to the authorize endpoint must be byte-for-byte one of the registered values — including scheme, host, port, trailing slash and path. https://app.example.com/cb does not match https://app.example.com/cb/.
• https:// is required, except for localhost and 127.0.0.1, where http:// is allowed so you can develop locally.
• No fragments. A URI containing # is rejected.
• No wildcards. A URI containing * is rejected outright — there is no pattern matching of any kind.
• Up to 10 per app, 512 characters each. Register one per environment rather than reusing a single URI with a switch inside it.

https://app.example.com/integrations/circa/callback
https://staging.example.com/integrations/circa/callback
http://localhost:3000/integrations/circa/callback

Query strings you need on the way back should go in the state parameter, not in the redirect URI — that keeps the registered list short and the match exact.

Scopes

Tick the scopes your app is allowed to ever request. An authorization request may ask for a subset of this list, never a superset — asking for something outside it fails before the user sees anything. Start with the minimum; you can add scopes later, and users who already authorized you will simply be asked again the next time you send them through the flow. See Scopes for what each one unlocks.

Client id and client secret

Saving the app issues both. The client id is public and identifies your app in the authorize URL. The client secret authenticates your server at the token endpoint and is a password in every meaningful sense.

client id      circa_cid_Vb3nT7yQ0sKp2mLxD9fA6cHu
client secret  circa_cs_9nQ2vJ0sYb4pR1tK7mLxD3fA6cHu8Zw5

Rotating the secret

Rotate secret on the app's page issues a new circa_cs_… value and records when the rotation happened. Rotate whenever a secret may have been exposed — a leaked .env, a departing contractor, a repo that was public for an afternoon. Existing access and refresh tokens are unaffected: rotation changes how your server authenticates to the token endpoint, not what your users consented to. Deploy the new secret promptly, because the old one stops working.

You can start immediately — review is only for the marketplace

A newly created app is in draft, and OAuth works from draft. You can run the full authorization flow, issue tokens and call the API without talking to anyone at Circa. App status gates marketplace visibility only, never token issuance.

The lifecycle:

• draft — fully functional. Anyone you send the authorize URL to can approve it.
• pending_review — you clicked Submit and Circa is reviewing the listing.
• approved — cleared for the marketplace. You then choose whether to actually list it.
• declined — returned with reviewer notes. Edit and resubmit.
• suspended — Circa has stopped the app. See Revoking access.

What Submit requires

Submitting for review is rejected until seven fields are filled in: name, tagline, description, logo, at least one redirect URI, at least one scope, and the privacy policy URL. The response names the ones you are missing. A terms of service URL, homepage URL and support email are optional.

Next

With a client id, a secret and at least one redirect URI, you are ready to run the authorization code flow.