Integration via Vendor API

The Vendor API is a universal, flexible, platform-agnostic mechanism for integrating apps with Setapp. The API was built for the systems that handle logic on the backend and thus require direct server-to-server communication with Setapp. The API can also be used for apps with only a web interface for users, Android apps, browser extensions, and many others.

The Vendor API consists of the Authorization API, which authenticates the app's client for communication with the Setapp system, and the Resource API, which allows performing the working operations with Setapp.

Authorization API

This API is used to authorize an app client to execute requests to the Vendor API on behalf of a Setapp user. The authorization process is based on the OAuth 2.0 Framework.

For more details, see the Authorization API Reference. However, we recommend reading the usage guide below first — to understand better how it all works.

Using the Authorization API

1. Register a client for your app and obtain clientId and clientSecret

Read how to add OAuth Client and view OAuth Client ID and OAuth Client Secret in our OAuth Clients article.

2. Get the authorization code

For macOS and iOS apps, you can use the Setapp Library (deprecated) and the Setapp Framework methods that return the auth code after performing the implicit authentication and authorization. These methods are:

• SCRequestAuthorizationCode for the Setapp Library (read more)
• requestAuthorizationCode for the Setapp Framework (read more)

For other platforms, we provide the Sign in with Setapp authentication.

Presently only application.access and ai.openai can be requested through the macOS Library or iOS Setapp Framework. If you request other scopes, an error will return.

3. Exchange the auth code for the access and the refresh tokens

For this operation, use the POST /token method in the Vendor API.

Having obtained the access token, you can start working with the Setapp Resource API.

4. Renew the access and the refresh tokens

Once the access token expires (its lifetime is 24 hours), exchange the refresh token for the new access and refresh tokens using the POST /token method with the "refresh_token" grant_type.

📘

Note

You can use each refresh token only once. So, ensure you use a new refresh token when renewing the access and the refresh tokens.

After the refresh token expires (its lifetime is 30 days), repeat the entire authorization flow starting from Step 2.

Resource API

Using the Resource API, you can perform the routine working operations with Setapp:

1. Provide access to the app for a user. In this request, we check if a user has an active Setapp subscription. We recommend executing the request every time a user accesses your app (signs in, starts a new session, activates an iOS app, etc.) — but not less than once in 24 hours.

2. Report app usage so the Setapp system can calculate your developer revenue. This report must be sent after a user utilizes your app's main functionality. We recommend not sending the report too often to avoid excessive server load; once an hour is enough.

   For more info, see the Implement usage reporting.

3. Get user info. This request will allow receiving the user’s id*, name, and email (name and email can only be requested using Sign in with Setapp). However, the response will not contain the subscription expiry date, and here’s why.

   The subscription expiry date itself is useless to handle because many other factors also affect the user’s subscription state, and even more factors form the permission to use apps. So, to make things simpler, we provide the “Access” request, the response to which clearly states that a user can use your app.

See the Resource API Reference for details.

• The user’s ID can also be retrieved from the access token itself. An access token is a JWT, so the user ID can be found in a "sub" field. If you don't need a username or email, there's no need to request the /userinfo.

📘

Rate limits

Vendor API has a rate limit of 24 requests per second for one IP. If you need more, please contact the support team.