> For the complete documentation index, see [llms.txt](https://taas-docs.stokr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://taas-docs.stokr.io/general-api-principles/authentication.md). # Authentication Our platform uses a multi-tenancy structure where all API access requires both **authentication** and **authorization**. This ensures secure, traceable access to your tokenization operations. ## oAuth provider We use [Firebase](https://firebase.google.com/) by Google for our OAuth service. You can work with their [APIs](https://firebase.google.com/docs/reference/rest/auth) directly or use their [SDK](https://firebase.google.com/docs/auth) for easier integration. ## Onboarding process During onboarding, we provide you with: * An admin user who can create additional users tailored to your integration needs * API key to communicate with Firebase. Since our system maintains comprehensive audit trails, we recommend creating granular user accounts to clearly track which person or system performed each action. ## **Authentication methods** Users can authenticate using one of two methods: `email` or `api_key` (see [Users and Roles](/api-overview/users-and-roles.md) for more details on user management). * **Email authentication:** Best when you don't have your own user management system or when users need to access our dashboards and UIs in addition to API. We provision an initial password through Firebase, which handles the login process for our interfaces and can serve as the authentication provider for custom UIs you build * **API key:** Ideal when you manage user authentication in your own systems or need API access for technical integrations. Users receive a refresh token that your systems can use when triggering API actions. This method works well for technical users like cron jobs, monitoring systems, and data synchronization services.
Common authentication scenarios * **You have an existing user management system**: Use API key authentication. Create a user for each person in your system and control which token is used for API calls to maintain clear audit trails. * **You build custom UIs for employees**: Use email authentication to leverage Firebase for user login management in your custom interface. * **Your employees use our dashboards and UIs**: Use email authentication so your team can log into our white-label interfaces. * **You integrate technical services**: For services like monitoring systems, data synchronization, schedulers, and other automated processes that use our API. Use API key authentication with separate tokens for different service types to maintain clear audit separation, especially for processes that make changes.
Regardless of which authentication method you choose, it allows you to use a refresh token to retrieve temporary access tokens (`access token` or `ID token` in Firebase terminology), which are necessary for authentication on our API. {% hint style="info" %} Our system logs all actions and changes according to the user credentials used. To get the most value from audit trails, create separate users for different people and systems - this lets you clearly identify who or what performed each action. See [Audit trails](/api-overview/common-data-concepts.md#audit-trails-fetching) section for more details {% endhint %} ### Firebase integration examples For complete implementation details, refer to the [Firebase API documentation](https://firebase.google.com/docs/reference/rest/auth). Here are the key steps: #### Obtaining refresh token {% tabs %} {% tab title="API key authentication" %} Create a user with `auth_type` set to `api_key`. We'll provide the refresh token directly in the response. {% endtab %} {% tab title="Email authentication" %} * Create a user with `auth_type` set to `email` and provide a valid email address. We'll generate an initial password and return it in the response. * Use this email and password with Firebase API to obtain your refresh token: ```json POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key= { "email": "user@email.io", "password": "password", "returnSecureToken": true } ``` ```json 200 OK { ... ... "refreshToken": "", ... } ``` {% endtab %} {% endtabs %} #### Obtaining access (id) token Once you have a refresh token (which doesn't expire), use it to request temporary access tokens through Firebase's API. ```json POST https://securetoken.googleapis.com/v1/token?key= { "grant_type": "refresh_token", "refresh_token": "" } ``` ```json 200 OK { "access_token": "", "expires_in": "3600", "token_type": "Bearer", ... } ``` These access tokens are what you'll use for actual API calls to our platform. ## Authenticating requests Include your valid access token as a `Bearer` token in the Authorization header for each API request:`Authorization: Bearer ` . Invalid or expired tokens will return a `401 Unauthorized` status, missing permissions for authentication user (authorization failure) will return a `403 Forbidden` . --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://taas-docs.stokr.io/general-api-principles/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.