> For the complete documentation index, see [llms.txt](https://docs.perkville.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville/authentication.md).

# Authentication

There are three primary options for developers to integrate their mobile app with Perkville. Please note that Perkville is integrated with some mobile applications out of the box such as with [Mariana Tek's mobile app ](https://www.marianatek.com/blog/perkville-loyalty-referral-integration/)and [ABC Fitness Ignite Engagement App](https://abcfitness.com/press-release/abc-fitness-partners-with-perkville-to-bring-fresh-features-and-opportunities-through-its-mobile-app/).

### 1. Simple Link or Button

Implement a simple link or button in your app that connects to Perkville’s mobile-optimized web experience. When the customer clicks the link or button, their browser, such as Chrome or Safari, opens so they can log in to Perkville and view their account. Perkville cookies the browser, so they usually do not need to log in again.

This method works well with partners like [Solution One](https://solutiononepartners.com/), as the customer will remain logged into Perkville in their browser, allowing the partner's single sign-on functionality with Perkville to continue working seamlessly.

### 2. PKCE OAuth

The benefit of this approach is that it provides a native experience without requiring server side development. However, the user does have to go through a one time [PKCE OAuth](https://www.perkville.com/developers/docs/v2/#v2_authorization_anchor_pkce_mobile_grant) flow for authentication. In this method, the customer [clicks a link in the mobile app](https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville/page-to-initiate-the-pkce-flow.md) to connect Perkville to the app. The customer is taken to a browser to complete the Oauth flow including logging into Perkville if they are not already signed in.

The resulting token is then securely stored in the app, which can be used to call [Perkville’s API](https://www.perkville.com/developers/docs/v2/) on behalf of the customer.

### 3. Use Admin Credentials

Store your business's Perkville admin credentials on your server and use these credentials to call [Perkville’s API](https://www.perkville.com/developers/docs/v2/) to fetch loyalty data for customers. This method allows the business to replicate the Perkville experience such as displaying earning rules, rewards as well as take actions on behalf of the customer such as joining the loyalty program and redeeming rewards but without the user having to register or login to Perkville.

The benefit of this approach is that you can provide a native experience without the user needing to complete the PKCE Oauth flow. However, it does require server side development because the business' admin credentials used to call Perkville's API in this approach, which can access all of the business' Perkville data, are not allowed to be stored on user's mobile apps.

### Hybrid approach

A hybrid approach is also possible. For example, you can use the PKCE OAuth flow or admin credentials to initially display the customer’s point balance while providing a link for other functionality. Over time, the loyalty program screens can be replicated within the app for a more integrated experience.

Regardless of which approach you choose, plan how you will store and reuse access tokens. PKCE tokens should be kept in secure device storage, while admin tokens must stay on your server and never be exposed to the mobile client.

***

### **Token Lifecycle**

Bearer tokens do not expire and there is no refresh token flow. Once you have an access token, store it and use it indefinitely.

The scenarios where a token can become invalid depend on which flow you are using:

* *PKCE:* A user can revoke access via their Perkville account settings. If this happens, you will need to put the user back through the OAuth consent flow to obtain a new token.
* *Resource Owner (Password) Grant:* A token only becomes invalid if your API client is deactivated (reserved for cases of abuse), or if the admin user associated with the token loses staff status at a business. If the password grant is run again for the same (client, admin user) pair, the existing token is overwritten and the previous token string is invalidated. Tokens for other admin users under the same client\_id are unaffected.

***

### **Platform Partners & Multi-Business Integrations**

If you are a platform that manages integrations across multiple businesses, the auth scheme you choose has implications for how you manage tokens and data isolation.

With **PKCE**, your single `client_id` can serve all businesses. Data isolation is handled naturally at the bearer token level. Each token is scoped to the individual user who granted access. Note that member enrollment (creating new connections) requires admin-level credentials regardless of which flow you use for the ongoing user experience, so PKCE alone is not sufficient if you need to register new members. The Hybrid approach noted above may be a better option for these cases.

With the **Resource Owner (Password) Grant**, tokens are issued per `(client_id, admin user)` pair. For multi-business platforms, there are a few approaches:

* **One admin user per business, shared client\_id -** Run the password grant once using credentials for a user who is an admin staff member at that business, and store the resulting token server-side for that business. When you onboard a new business, generate a new token using that business's admin credentials. No new client registration needed. Data isolation is handled naturally since each token is scoped to its own admin user. Note that if a business's admin account loses staff status or is deactivated, that business's integration will break. We recommend using a stable service account rather than a personal employee account.
* **Single admin user across all businesses** - One token, but that user must maintain staff status at every business. If they are removed from any business, that business's integration will silently break. Because this token has access to data from all connected businesses simultaneously, your integration is responsible for data separation — use business filters on every API request.
* **One client registration per business** — A separate `client_id` per business provides the strictest data isolation, but requires registering a new client with Perkville each time you onboard a new business.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
