# Getting Access

You register your app in the **developer portal**, signed in with your
Precision Cut Archery account, and get a `client_id` at once. Registering
needs your acceptance of the [Developer Agreement](/developer-agreement/#registration),
which the portal records when you click **I agree**. It doesn't need a
subscription.

**[Open the developer portal →](/app/developers/)**

Every call acts for a PCA user who has granted your app consent, so there
is no client-credentials flow. A script registers like any other app and
uses the authorization-code flow with refresh tokens.

## One registration per product

Register once per company or product, not once per platform. Your web
app, iOS app, Android app and backend share one `client_id`, with every
platform's redirect URIs and web origins on it. One person then has one
`pca_subject` across your platforms and your app shows once in their
Connected Apps.

A client ID has an **optional secret**, not a type. An app with no secret
relies on PKCE alone, which suits a phone or a browser. An app with a
backend adds a secret the backend sends when it exchanges a code or
refreshes. See [Secrets](#secrets) and [Redirect
URIs](#redirect-uris-backend-and-app).

## Register your app

Choose **Register an app**. The form explains each field and its
**Preview listing** button shows the consent screen your users will see. You get a
generated `client_id`.

- Your account's email is the app's first test account. One account can
  register up to five apps.
- A new app starts in **development**, at the development [rate
  limit](#rate-limits).
- One account owns each app. To transfer one, email
  **support@precisioncutarchery.com**.
- The contact email also gets notice of incidents and of changes to the
  API, so use an address someone reads.
- If you say the app has a backend, we create its first client secret.

### Hybrid apps

A Capacitor or Ionic app calls the API from a web view whose origin is
fixed by its framework. Register the ones yours uses:
`capacitor://localhost` or `ionic://localhost` on iOS, and
`https://localhost` or `http://localhost` on Android. Other frameworks'
origins, such as Cordova's, Electron's or Tauri's, we register on
request. A `null` origin can't be registered.

Every app built on that framework sends the same origin, so it doesn't
identify your app: the user's access token is what authenticates each
call. A hybrid app's redirect URI is a mobile app's, a private-use scheme
or an app-claimed `https` link.

## Secrets

A client secret starts with `pcc_cs_`. The portal shows it once and keeps only a hash, so create a new one
if you lose it. Keep it out of anything you ship to a browser or device
([Developer Agreement](/developer-agreement/#registration)).

An app holds up to two active secrets, so you can rotate without
downtime: create the new one, deploy it, then retire the old one.

If you revoke your app's last secret, your backend redirect URIs stay as
they are, and codes sent to them fail until you create a new client secret.

A secret that doesn't verify is always `401 invalid_client`: a wrong,
revoked or expired one, or any secret sent to an app that has none. It
never falls back to PKCE alone.

## Redirect URIs: backend and app

Each redirect URI is marked for your **backend** or for an **app**:

- A **backend** redirect URI is `https` or loopback `http`, and needs the
  app to hold an active secret. A code issued to it is exchanged only
  with the secret.
- An **app** redirect URI is for a phone, a desktop app or a browser
  with no backend. Its code is exchanged with or without a secret.

Redirect URIs show in the browser's address bar during sign-in, so put
nothing secret in one. A loopback URI is `http` on `127.0.0.1` or `[::1]`
and never `localhost` (see [Testing locally](#testing-locally)).

## Mobile app with a backend

The phone signs in on its own with PKCE, on an app redirect URI, and keeps
its own tokens. Whether a sign-in was made with a secret is set once, by
the code exchange:

- A sign-in made with a secret refreshes and revokes only with it. A
  backend can't hand its refresh token to a phone: the phone's refresh is
  `401 invalid_client`.
- A PKCE-only sign-in never upgrades, whatever sends its refresh token. A
  secret that is sent must still verify.

A phone can instead hand its authorization code to your backend, which
exchanges it with the secret and the PKCE verifier. That sign-in is the
backend's. A private-use scheme (`com.example.app:/…`) can't be a backend
redirect URI.

## Development mode

There is no sandbox or test server: you test against the real API. In
development, only your app's **test accounts** and PCA's reviewers can
connect it. Test accounts are up to six existing Precision Cut Archery
accounts, set in the portal by email address. Anyone else sees that the
app is in development, and your app gets `access_denied`.

- Each test account needs a **normal, entitled Precision Cut Archery
  subscription** (trialing or active). Connect grants no free or test
  subscriptions.
- PCA's reviewers use our own reviewer accounts, which take none of your
  six slots.
- To test a lapsed subscription, ask us to switch a test account to
  lapsed, and back when you're done. Your app should show a renew prompt on
  `402` or `active: false` from the [subscription
  check](/documentation/developers/calling-the-api/#subscription-check).

## Testing locally

One registration covers local development: you don't need a second app.

- **Redirect URI:** register `http://127.0.0.1/callback` (or
  `http://[::1]/callback`) alongside your production URIs. Any port
  matches at authorization time, so your dev server can run on any port;
  the path must match. `localhost` is never accepted as a redirect URI.
- **Web origin:** register your local page's origin, port included, such
  as `http://127.0.0.1:5500`. An `http` web origin is allowed only on the
  local host. Open your page on the host your redirect URI names, or what
  it keeps in `sessionStorage` is missing on the callback
  ([Quickstart](/documentation/developers/quickstart/)).

A live app keeps its loopback redirect, so you can go on developing
locally against it.

## Review and going live

When your app is ready, request review in the portal. We review it and
decide whether and when it goes live ([Developer Agreement, Section
3](/developer-agreement/#going-live)).

1. Build and test in development mode.
2. In your app, tell users how to reach you for support, and link to the
   page where they can disconnect your app:
   `https://www.precisioncutarchery.com/app/account/connected-apps/`
   ([Developer Agreement, Section 6](/developer-agreement/#end-users)).
3. Choose **Request review**. It needs a logo and a privacy policy URL.
   Tell us in the description how our reviewers can sign in, and your
   expected traffic and launch date. We usually review within 3 business
   days and email your contact address the outcome.
4. We may reject it with a reason, which the portal shows in the revision
   history. Edit the listing and request review again.
5. Once approved, the app is **approved, awaiting go-live**. We then set
   it to **live**, and any subscriber can connect it.

A suspended app stops working on its next request, and each user connects
again once it is lifted
([Developer Agreement](/developer-agreement/#termination)).

### Revisions

A request freezes the listing as a revision, locked until we decide it or
you withdraw it. Until the first approval, your edits apply directly. After
one, edits go to a draft, and users keep seeing the approved listing until a
revision is approved.

Redirect URIs, origins and the contact email apply when you save them and
aren't reviewed.

## Rate limits

These are the current values; they may change
([Developer Agreement](/developer-agreement/#changes)). Your app's rate is
on its page in the portal, under Credentials: 60 a minute in development
and 600 live.

- Your app's share for one user is the lower of your app's rate and 60 a
  minute.
- A user's budget for an area is shared by every app they use:
  `analyze` 1000 a minute, and `build`, `air` and `subscription-status`
  300 each.
- `/oauth/authorize` allows 30 a minute per IP address.
- To ask for a higher rate, email **support@precisioncutarchery.com** with
  your client ID and the traffic you expect.

Past a limit, a call gets `429` with `Retry-After`;
[Errors](/documentation/developers/errors/#rate-limits) shows what to do.
For a failed call, include its [request
ID](/documentation/developers/errors/#request-ids).
