An API key is fine for an internal integration: one account, one script, one key. As soon as your software targets several Grand Shooting customers, use an OAuth application (called "plugin" in the API):

• the user signs in to Grand Shooting and authorizes your application, without giving you a password or a key;
• your application receives a token specific to that account;
• the account activates and deactivates your application from its Connectors page.

Declaring an application

An application belongs to the account of its vendor. It is defined by:

Item	Role
client_id, client_secret	OAuth credentials of the application, provided by Grand Shooting. The secret must never leave your server.
Callback URL (redirect_uri)	Address where Grand Shooting sends the user back after the authorization. It must exactly match the one sent in the request (local addresses localhost / 127.0.0.1 are accepted on any port, for development).
Activation URL	Page of your application opened when an account activates the connector: it starts the OAuth flow.
Poll status URL	Polled during the activation to show the progress to the user.
Deactivation URL	Called when the account deactivates the connector.

These URLs are set in the Grand Shooting developer portal, where you also find your client_id and can renew the client_secret. To create an application and make it available to customer accounts, contact the Grand Shooting team (help@grand-shooting.com).

The authorization flow

Grand Shooting implements the OAuth 2.0 Authorization Code flow, with optional, recommended PKCE (S256). The authorization server is https://api.grand-shooting.com/oauth/default; its metadata is published at https://api.grand-shooting.com/.well-known/oauth-authorization-server.

1. Redirect the user

GET https://api.grand-shooting.com/oauth/default/authorize
  ?response_type=code
  &client_id=gs_123_xxxxxxxx
  &redirect_uri=https%3A%2F%2Fmyapp.example%2Fcallback
  &state=<random value>
  &code_challenge=<challenge>&code_challenge_method=S256

The user signs in to Grand Shooting, then accepts or refuses the access. If they accept, they come back to your redirect_uri with ?code=…&state=…; if they refuse, with ?error=access_denied&state=…. Always check that state is the one you sent.

2. Exchange the code for a token

The code can be used once: exchange it right away, from your server.

curl -X POST https://api.grand-shooting.com/oauth/default/token \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://myapp.example/callback \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d code_verifier=$VERIFIER

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 31536000,
  "refresh_token": "…",
  "account_id": 10229487
}

The access token and the refresh token are valid for one year. Store them per account_id: the same user of your software can connect several Grand Shooting accounts.

3. Call the API

The OAuth token is sent with the access_token prefix, not Bearer (reserved for API keys):

curl -H "Authorization: access_token $ACCESS_TOKEN" https://api.grand-shooting.com/v3/account/me

The whole API is then available, as with a key: see Getting started with the API. GET https://api.grand-shooting.com/oauth/default/user/info (with Authorization: Bearer <access_token>) returns the user and the account that authorized the application.

4. Refresh the token

curl -X POST https://api.grand-shooting.com/oauth/default/token \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

Each refresh returns a new pair of tokens and invalidates the old refresh token: always store the new pair.

There are no scopes: the token gives the application the rights of the user who authorized it, on their account. Ask your customers to authorize the application with a user whose rights match what it needs.

Activation from the Connectors page

On the customer side, the installation takes a few clicks:

1. In the Connectors page of their account, the user activates your application.
2. Grand Shooting opens your activation URL (with plugin_id as a parameter), which redirects to /authorize (step 1 above).
3. Meanwhile, the Connectors page polls your poll status URL every two seconds (with account_id, plugin_id and user_uid); it expects a JSON status wait, pick, ok or error.
4. Once the token is obtained, your server confirms the activation for that account:

curl -X PATCH -H "Authorization: access_token $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"active":true}' https://api.grand-shooting.com/v3/account/plugin/{plugin_id}

On deactivation, Grand Shooting calls your deactivation URL with DELETE, with account_id as a parameter: delete the tokens of that account.

Going further

• Your application can subscribe to the account's webhooks with its token, to react to new media without polling the API.
• The Grand Shooting MCP server uses the same authorization server: it is an OAuth application like any other.