Skip to content

OAuth apps

An API key automates your own account. If you are building a product that schedules for other Sharek accounts, use OAuth instead: they approve your app on a Sharek consent screen, and you get a token that acts for them. You never handle their key. To connect your own AI tool you need no app at all: follow connect your AI tool.

An OAuth token reaches exactly the same operations as an API key, and the API overview covers the base address, limits and error shapes both share.

  1. Someone using your product clicks your “Connect Sharek” button.
  2. You send them to the Sharek authorization screen with your client id.
  3. Sharek shows a consent screen naming your app, and they approve or deny.
  4. Sharek sends them back to your redirect URL with a short-lived code.
  5. Your server exchanges that code for an access token.
  6. You call the API with the token.

Steps 2 and 4 happen in their browser. Step 5 happens on your server, because it needs your client secret.

Each organization can have one OAuth app, and managing it takes the Admin or Super Admin role on an account with API access. Anyone else who opens the Apps tab sees only Approved Apps.

  1. Open Sharek, go to Settings, then the Apps tab.

  2. Create an app. You provide an App Name (shown on the consent screen), an optional Description and Profile Picture, and a Redirect URL where Sharek returns people after they decide.

  3. Sharek issues a client id prefixed pca_ and a client secret prefixed pcs_.

Redirect them to the Sharek authorization screen:

https://dash.sharek.app/oauth/authorize?client_id=pca_your_client_id&response_type=code&state=random-string
Parameter Required Description
client_id Yes Your app’s client id.
response_type Yes Must be code.
state No A random string you generate per attempt. Strongly recommended: it is how you detect a forged callback.

They see your app’s name, description and picture, and choose Authorize or Deny.

Sharek sends them back to your registered redirect URL.

Approved:

https://your-app.example/callback?code=the-code&state=random-string

Denied:

https://your-app.example/callback?error=access_denied&state=random-string

Compare the returned state against the one you generated before you do anything else. If it does not match, drop the request.

Server-side, because this call carries your secret:

Terminal window
curl -X POST https://dash.sharek.app/api/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "authorization_code",
"code": "the-code-from-the-callback",
"client_id": "pca_your_client_id",
"client_secret": "pcs_your_client_secret"
}'
Field Required Description
grant_type Yes Must be authorization_code.
code Yes The code from the callback.
client_id Yes Your app’s client id.
client_secret Yes Your app’s client secret.

You can send client_id and client_secret in an Authorization: Basic header instead, as the base64 of client_id:client_secret, and leave them out of the body.

A successful exchange answers 200:

{
"id": "organization-id",
"cus": "billing-customer-id",
"access_token": "pos_your_oauth_token",
"token_type": "bearer",
"scope": "mcp:read mcp:write"
}
Field Description
id The organization the token acts for. Store it alongside the token.
cus That organization’s billing customer id.
access_token The token, prefixed pos_.
token_type Always bearer.
scope Always mcp:read mcp:write for an app you register. Informational only: the token reaches every public API operation whatever it says.

Same header as an API key, and still no Bearer prefix even though token_type says bearer:

Terminal window
curl -H "Authorization: pos_your_oauth_token" \
https://dash.sharek.app/api/public/v1/integrations

A good first call is get the current account: it names the person who approved your app and their organization, so you can show who is connected.

Access tokens do not expire on a timer. They stop working when the person revokes your app, or when you delete it.

Rotate the secret if it leaks. The old secret stops working immediately. Existing access tokens keep working, because only the token exchange uses the secret.

Delete the app and every token it ever issued is revoked, and it disappears from everyone’s approved apps. There is no undo.

Error When Status Meaning
access_denied On the callback None They chose Deny. Not an error to retry.
invalid_client Token exchange 401 The client id or secret is wrong or missing.
invalid_grant Token exchange 400 The code is unknown, already used, or belongs to another app.
invalid_grant with error_description: "Code has expired" Token exchange 400 More than 10 minutes passed. Restart the flow.
unsupported_grant_type Token exchange 400 grant_type was not authorization_code.