{team.displayName}
Team ID: {team.id}
All teamsAPI Key: {apiKey.value}
;
}
```
Team not found
;
}
const teamApiKey = await team.createApiKey({
description: "Admin-provisioned team API key",
expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30 days
});
return Team API Key: {teamApiKey.value}
;
}
```
API Key: {apiKey.value}
;
}
```
Team not found
;
}
const teamApiKey = await team.createApiKey({
description: "Admin-provisioned team API key",
expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30 days
});
return Team API Key: {teamApiKey.value}
;
}
```
Your API Keys
{apiKeys.map(key => ({key.description}
Last 4 digits: {key.value.lastFour}
Created: {key.createdAt.toLocaleDateString()}
Your API Keys
{apiKeys.map(key => ({key.description}
Last 4 digits: {key.value.lastFour}
Created: {key.createdAt.toLocaleDateString()}
Your API Keys
{apiKeys.map(key => ({key.description}
Last 4 digits: {key.value.lastFour}
Created: {key.createdAt.toLocaleDateString()}
API key not found
;
}
if (apiKey.isValid()) {
return API key is valid
;
}
const reason = apiKey.whyInvalid();
return API key is invalid: {reason}
;
}
```
User not found
;
const apiKeys = await user.listApiKeys();
const apiKey = apiKeys.find(key => key.id === apiKeyId);
if (!apiKey) {
return API key not found
;
}
if (apiKey.isValid()) {
return API key is valid
;
}
const reason = apiKey.whyInvalid();
return API key is invalid: {reason}
;
}
```
API key not found
;
}
if (apiKey.isValid()) {
return API key is valid
;
}
const reason = apiKey.whyInvalid();
return API key is invalid: {reason}
;
}
```
Google account connected
;
}
```
## Providing scopes
Most providers have access control in the form of OAuth scopes. These are the permissions that the user will see on the authorization screen (eg. "Your App wants access to your calendar"). For instance, to read Google Drive content, you need the `https://www.googleapis.com/auth/drive.readonly` scope:
```jsx theme={null}
'use client';
import { useUser } from "@hexclave/next"; // replace `next` with the correct framework SDK package
export default function Page() {
const user = useUser({ or: 'redirect' });
// Redirects to the Google authorization page, requesting access to Google Drive
const account = user.useConnectedAccount('google', { or: 'redirect', scopes: ['https://www.googleapis.com/auth/drive.readonly'] });
// Account is always defined because of the redirect
return Google Drive connected
;
}
```
Check your provider's API documentation to find a list of available scopes.
## Retrieving the access token
Once connected with an OAuth provider, obtain the access token with the `account.getAccessToken()` function. Check your provider's API documentation to understand how you can use this token to authorize the user in requests.
```jsx theme={null}
'use client';
import { useEffect, useState } from 'react';
import { useUser } from "@hexclave/next"; // replace `next` with the correct framework SDK package
export default function Page() {
const user = useUser({ or: 'redirect' });
const account = user.useConnectedAccount('google', { or: 'redirect', scopes: ['https://www.googleapis.com/auth/drive.readonly'] });
const { accessToken } = account.useAccessToken();
const [response, setResponse] = useState{response ? JSON.stringify(response) : 'Loading...'}
;
}
```
## Sign-in default scopes
To avoid showing the authorization page twice, you can already request scopes during the sign-in flow. This approach is optional. Some applications may prefer to request extra permissions only when needed, while others might want to obtain all necessary permissions upfront.
To do this, edit the `oauthScopesOnSignIn` setting of your `hexclaveServerApp`:
```jsx title="stack/server.ts" theme={null}
export const hexclaveServerApp = new HexclaveServerApp({
// ...your other settings...
oauthScopesOnSignIn: {
google: ['https://www.googleapis.com/auth/drive.readonly']
}
});
```
## OAuth account merging strategies
When a user attempts to sign in with an OAuth provider that matches an existing account, Stack provides different strategies for handling the authentication flow.
The available strategies are:
* Allow duplicates (legacy default)
* Link method (new default)
* Block duplicates (most secure)
The "Link" strategy is the default behavior. If a user attempts to sign in with an OAuth provider that matches an existing account, Stack will link the OAuth identity to the existing account, and the user will be signed into that account.
This requires both of the credentials to be verified, or otherwise the link will be blocked, in the same way as the "Block" strategy.
The "Allow" strategy is the default behavior for old projects. If a user attempts to sign in with an OAuth provider that has an existing account with the same email address, Stack will create a separate account for the user.
The "Block" strategy will explicitly raise an error if a user attempts to sign in with an OAuth provider that matches an existing account.
# JWT Tokens
Source: https://docs.hexclave.com/guides/apps/authentication/jwts
Understand how Hexclave uses JSON Web Tokens for authentication
JSON Web Tokens (JWT) are a compact, URL-safe means of representing claims to be transferred between two parties. Hexclave uses JWTs for secure authentication and authorization.
You don't need to worry about JWTs if you're using Hexclave. However, if you are an expert user and want the full flexibility to manually verify JWTs for performance or other reasons, this page is for you.
## What is a JWT?
A JWT is a string that consists of three parts separated by dots (`.`):
1. **Header**: Contains metadata about the token, such as the signing algorithm
2. **Payload**: Contains the claims (data) about the user or entity
3. **Signature**: Used to verify the token's authenticity
The structure looks like this: `header.payload.signature`
## Hexclave JWT Structure
Hexclave JWTs contain standardized headers and claims that power authentication throughout the platform.
### Header
* **`alg`**: Always `ES256`
* **`kid`**: Identifies which public key from the JWKS should be used for verification
### Standard Claims
* **`iss` (Issuer)**: `https://api.hexclave.com/api/v1/projects/Please sign in
;
}
return Welcome, {user.displayName}!
;
}
```
**React:**
```tsx theme={null}
import { useUser } from '@hexclave/react';
export function UserProfile() {
const user = useUser();
if (!user) {
return Please sign in
;
}
return Welcome, {user.displayName}!
;
}
```
### Server-Side Usage
On the server side, you can access the JWT and its claims through the Hexclave API:
```typescript theme={null}
import { hexclaveServerApp } from '@/stack';
export async function GET() {
const user = await hexclaveServerApp.getUser();
if (!user) {
return new Response('Unauthorized', { status: 401 });
}
// Access user information from the JWT
return Response.json({
id: user.id,
displayName: user.displayName,
primaryEmail: user.primaryEmail,
selectedTeamId: user.selectedTeamId,
// Other user properties...
});
}
```
### Manual JWT Verification
If you need to manually verify a JWT (for example, in a different service), fetch the public keys from Hexclave's JWKS endpoint. Keys are derived per audience so the `kid` in the JWT header always matches one of the published keys.
```typescript theme={null}
import * as jose from 'jose';
// Get the public key set from Hexclave
const jwks = jose.createRemoteJWKSet(
new URL('https://api.hexclave.com/api/v1/projects/YOUR_PROJECT_ID/.well-known/jwks.json')
);
// Verify a regular (non-anonymous) access token
try {
const { payload } = await jose.jwtVerify(token, jwks, {
issuer: 'https://api.hexclave.com/api/v1/projects/YOUR_PROJECT_ID',
audience: 'YOUR_PROJECT_ID',
});
console.log('JWT is valid:', payload);
} catch (error) {
console.error('JWT verification failed:', error);
}
```
To support anonymous sessions, include those keys and allow both issuers and audiences:
```typescript theme={null}
import * as jose from 'jose';
const jwks = jose.createRemoteJWKSet(
new URL('https://api.hexclave.com/api/v1/projects/YOUR_PROJECT_ID/.well-known/jwks.json?include_anonymous=true')
);
const { payload } = await jose.jwtVerify(token, jwks, {
issuer: [
'https://api.hexclave.com/api/v1/projects/YOUR_PROJECT_ID',
'https://api.hexclave.com/api/v1/projects-anonymous-users/YOUR_PROJECT_ID',
],
audience: ['YOUR_PROJECT_ID', 'YOUR_PROJECT_ID:anon'],
});
```
To support restricted users (e.g., users who haven't verified their email), add `include_restricted=true`:
```typescript theme={null}
import * as jose from 'jose';
const jwks = jose.createRemoteJWKSet(
new URL('https://api.hexclave.com/api/v1/projects/YOUR_PROJECT_ID/.well-known/jwks.json?include_anonymous=true&include_restricted=true')
);
// All three user types have different issuers
const { payload } = await jose.jwtVerify(token, jwks, {
issuer: [
'https://api.hexclave.com/api/v1/projects/YOUR_PROJECT_ID',
'https://api.hexclave.com/api/v1/projects-anonymous-users/YOUR_PROJECT_ID',
'https://api.hexclave.com/api/v1/projects-restricted-users/YOUR_PROJECT_ID',
],
audience: ['YOUR_PROJECT_ID', 'YOUR_PROJECT_ID:anon', 'YOUR_PROJECT_ID:restricted'],
});
```
### Signing Keys
* Private keys are deterministically derived from your project ID, optional anonymous audience, and the `STACK_SERVER_SECRET` environment variable. This means no key material is ever stored in the database.
* The JWKS currently exposes both the latest key pair and a legacy compatibility key. Verification libraries automatically pick the correct key by matching the `kid` provided in the JWT header.
* Tokens are always signed server-side; client SDKs never receive the private keys.
## Security Considerations
### Token Storage
* **Never store JWTs in localStorage** for sensitive applications
* Use secure, httpOnly cookies when possible
* Hexclave handles secure token storage automatically
### Token Expiration
* JWTs have a limited lifetime (default is 10 minutes via `STACK_ACCESS_TOKEN_EXPIRATION_TIME`)
* Hexclave automatically refreshes tokens before they expire
* Always check the `exp` claim when manually handling JWTs
### Signature Verification
* Always verify JWT signatures using the public key
* Never trust the contents of a JWT without verification
* Hexclave SDKs handle verification automatically
## Troubleshooting
### Common Issues
1. **"JWT is expired"**: The token has passed its expiration time. Hexclave will automatically refresh it.
2. **"Invalid signature"**: The token was tampered with or signed with a different key.
3. **"Invalid audience"**: The token was issued for a different project or environment.
### Debugging JWTs
Use a JWT viewer such as [jwt.io](https://jwt.io/) to inspect tokens and verify their contents. Pay special attention to:
* Expiration times (`exp` claim)
* Audience (`aud` claim) matching your project
* Required claims are present
## Best Practices
1. **Let Hexclave handle tokens**: Use the provided SDKs instead of manual JWT handling
2. **Validate on the server**: Always verify JWTs on your backend
3. **Check expiration**: Ensure tokens haven't expired before using them
4. **Use HTTPS**: Always transmit JWTs over secure connections
5. **Monitor token usage**: Log authentication events for security monitoring
## Related Concepts
* [API Keys](/guides/apps/api-keys/overview) - Alternative authentication method for server-to-server communication
* [Setup](/guides/getting-started/setup) - How to verify user sessions in your backend
* [Permissions](/guides/apps/rbac/overview) - Understanding user permissions (not included in JWTs)
* [Teams](/guides/apps/teams/overview) - Understanding team context in JWTs
# Authentication
Source: https://docs.hexclave.com/guides/apps/authentication/overview
Integrate Hexclave with AI-powered tools and services
TODO stub
# Restricted Users
Source: https://docs.hexclave.com/guides/apps/authentication/restricted-users
Understand and handle users with limited access
Restricted users are signed-in users whose account exists, but has not been granted normal application access yet. Stack marks these users with `user.isRestricted === true` and provides a `user.restrictedReason` explaining why.
By default, Hexclave treats restricted users like unauthenticated users in most SDK calls. This prevents accounts that still need verification, review, or conversion from accidentally getting access to protected product flows.
## When users are restricted
Users can be restricted for a few reasons:
* **Email not verified**: the project requires email verification before full access.
* **Anonymous user**: anonymous users can interact with the app, but are always restricted until converted.
* **Restricted by administrator**: the user was restricted manually or by a [sign-up rule](/guides/apps/authentication/sign-up-rules).
You can inspect the reason from the SDK:
```ts my-app.ts theme={null}
import { hexclaveServerApp } from "../src/stack/server";
const user = await hexclaveServerApp.getUser({ includeRestricted: true });
if (user?.isRestricted) {
console.log(user.restrictedReason?.type);
}
```
The current `restrictedReason.type` values are:
| Type | Meaning |
| ----------------------------- | ------------------------------------------------------ |
| `email_not_verified` | The user still needs to verify their email address. |
| `anonymous` | The user is an anonymous user. |
| `restricted_by_administrator` | The user was restricted manually or by a sign-up rule. |
## Loading restricted users
Most calls exclude restricted users unless you explicitly opt in. Use `includeRestricted: true` when you are building onboarding, email verification, account review, or anonymous-user conversion flows.
Welcome back, {user.displayName ?? user.primaryEmail}
;
}
```
Please verify your email address to continue.
;
}
if (reason === "anonymous") {
return Create an account to save your progress.;
}
return Your account is waiting for review.
;
}
```
For API routes or backend actions, keep using the default behavior unless the endpoint is specifically meant to serve restricted users. This helps prevent partially onboarded accounts from reaching product APIs.
## Restricted users in JWTs
Restricted users receive tokens with `is_restricted` and `restricted_reason` claims. If your backend verifies Hexclave JWTs directly, make sure you reject restricted users unless the endpoint intentionally supports them.
When fetching Hexclave's JWKS, restricted-user signing keys are excluded by default. Include them only for services that intentionally accept restricted users:
```txt jwks-url.txt theme={null}
/.well-known/jwks.json?include_restricted=true
```
If you also accept anonymous users, use `include_anonymous=true`; anonymous keys imply restricted-user keys.
## Admin and sign-up review
Sign-up rules can restrict a user instead of rejecting the sign-up outright. This is useful when you want the account to exist, but need manual review before granting access.
For more details on creating rules that restrict users, see [Sign-up Rules](/guides/apps/authentication/sign-up-rules).
# Sign-up Rules
Source: https://docs.hexclave.com/guides/apps/authentication/sign-up-rules
Control who can sign up for your application with customizable rules.
Sign-up rules let you control who can sign up for your application. You can create rules that evaluate sign-up attempts based on conditions like email domain or authentication method, then allow, reject, or restrict users accordingly.
Rules are evaluated during sign-up for all authentication methods (password, magic link, OAuth, passkey). When a user attempts to sign up, Stack evaluates each rule in priority order—the first matching rule determines the outcome. If no rules match, the default action is used.
## Creating rules
Navigate to **Sign-up Rules** in your project dashboard to create and manage rules.
To add a rule:
1. Click **Add Rule**
2. Enter a name for your rule (e.g., "Block disposable emails")
3. Configure the conditions using the visual builder
4. Select an action (Allow, Reject, Restrict, or Log)
5. Click **Create rule**
### Available conditions
When building rule conditions, you have access to these context variables:
| Variable | Type | Description |
| --------------- | ------ | --------------------------------------------------------------------------------------- |
| `email` | string | The user's email address (normalized to lowercase) |
| `emailDomain` | string | The domain part of the email (after @) |
| `authMethod` | string | The authentication method: `password`, `otp`, `oauth`, or `passkey` |
| `oauthProvider` | string | The OAuth provider ID if using OAuth (e.g., `google`, `github`), empty string otherwise |
The condition builder supports these operations on string values:
* `contains("substring")` - Check if value contains a substring
* `startsWith("prefix")` - Check if value starts with a prefix
* `endsWith("suffix")` - Check if value ends with a suffix
* `matches("regex")` - Check if value matches a regular expression
* `==` and `!=` - Exact equality comparisons
You can combine multiple conditions using AND/OR logic.
## Actions
### Allow
The user signs up normally. Use this to explicitly allow certain users when your default action is set to reject.
### Reject
Blocks the sign-up and shows the user: "Your sign up was rejected by an administrator's sign-up rule." You can optionally add an internal message for logging (not shown to users).
### Restrict
The user signs up, but their account is marked as restricted. Restricted users have limited access and can be reviewed by admins before gaining full access. See [JWT Tokens](/guides/apps/authentication/jwts) for how restricted status appears in tokens.
### Log
The rule is triggered and logged for analytics, but no action is taken. Use this to monitor patterns before implementing blocking rules.
## Priority and default action
Rules are evaluated in priority order (highest first). You can reorder rules by dragging them in the dashboard. Only the first matching rule's action is applied, so place your allow rules before reject rules if you want to allow specific users while blocking others.
The default action applies when no rules match:
* **Allow** (default): Sign-ups are allowed unless a rule explicitly rejects them
* **Reject**: Sign-ups are blocked unless a rule explicitly allows them
Set the default to "Reject" when you want to only allow sign-ups from specific domains.
## Common use cases
### Block disposable email domains
Block users signing up with temporary email addresses:
* Condition: `emailDomain.matches("(tempmail|throwaway|guerrillamail)\\..*")`
* Action: Reject
### Allow only corporate domains
1. Set default action to **Reject**
2. Create an allow rule with condition: `emailDomain == "company1.com" || emailDomain == "company2.com"`
### Restrict non-verified auth methods
Require manual review for users who sign up without email verification:
* Condition: `authMethod == "oauth" && oauthProvider != "google"`
* Action: Restrict
### Different rules for different auth methods
Allow password sign-ups from any domain, but restrict OAuth sign-ups:
1. Rule 1: `authMethod == "password"` → Allow
2. Rule 2: `authMethod == "oauth"` → Restrict
3. Default: Allow
## Analytics
The dashboard shows analytics for each rule, including how many times it's been triggered over the past 48 hours. Use this to understand your sign-up patterns and tune your rules.
## Testing rules
You can test your sign-up rules using the built-in rule tester. It simulates sign-up requests and shows which rules would trigger and what the outcome would be—without affecting real users.
To open the tester, scroll to the bottom of the Sign-up Rules page and click **Open tester**.
### Test inputs
Enter the following to simulate a sign-up attempt:
* **Email**: The email address to test (e.g., `user@company.com`)
* **Auth method**: The authentication method (`Password`, `OTP`, `OAuth`, or `Passkey`)
* **OAuth provider**: The OAuth provider ID (only used when auth method is OAuth)
Click **Run test** to see the results.
### Understanding the results
The tester displays:
* **Outcome**: Whether the sign-up would be allowed or rejected, and whether the decision came from a specific rule or the default action.
* **Triggered rules**: All rules that matched the test input, showing each rule's name, condition, action type, and whether it was the deciding rule.
* **Evaluation trace**: A detailed view of how every rule was evaluated—which matched, which didn't, which were disabled, and any errors.
* **Normalized context**: How the test input was parsed, including the extracted email domain. Useful for debugging conditions that reference `email`, `emailDomain`, `authMethod`, or `oauthProvider`.
# User Onboarding
Source: https://docs.hexclave.com/guides/apps/authentication/user-onboarding
Implementing a user onboarding page and collecting information on sign-up
Sometimes, you may want to collect additional information from users during sign-up, for example a real name or address.
The most straightforward approach is to redirect users to an onboarding page right after they sign up. However, this is not recommended for the following reasons:
1. Users can accidentally (or purposefully) close or navigate away from the page before completing the onboarding.
2. Redirect URLs may vary depending on the context. For instance, if a user is redirected to a sign-in page after trying to access a protected page, they'll expect to return to the original protected page post-authentication.
Instead, a more reliable strategy is to store an `onboarded` flag in the user's metadata and redirect users to the onboarding page if they haven't completed it yet.
## Example implementation
Let's say you have an onboarding page that asks for an address and stores it in the user's [metadata](/guides/getting-started/user-fundamentals#custom-metadata):
```jsx theme={null}
export default function OnboardingPage() {
const user = useUser();
const router = useRouter();
const [address, setAddress] = useState('');
return <>
setAddress(e.target.value)}
/>
);
}
```
Welcome to the app, {user.displayName}
);
}
```
Welcome to the app, {user.displayName}
);
}
```
Welcome!
Thanks for joining us.
', }); ``` ### Send to all users ```typescript theme={null} await hexclaveServerApp.sendEmail({ allUsers: true, templateId: 'your-template-id', subject: 'We just shipped a big update', variables: { featureName: 'Dark mode', }, }); ``` ### Send from a dashboard draft If you've composed an email in the dashboard's draft editor, you can trigger it programmatically: ```typescript theme={null} await hexclaveServerApp.sendEmail({ userIds: ['user-id'], draftId: 'your-draft-id', }); ``` ### Full options ```typescript theme={null} await hexclaveServerApp.sendEmail({ // Recipients - exactly one of these is required: userIds: ['user-id-1'], // specific users // allUsers: true, // or all users in your project // Content - exactly one of these is required: html: 'Hello!
', // raw HTML // templateId: 'template-id', // or a template with variables // draftId: 'draft-id', // or a dashboard draft // Optional: subject: 'Hello!', variables: { key: 'value' }, themeId: 'theme-id', // apply a specific theme // themeId: null, // use the default theme // themeId: false, // send with no theme at all notificationCategoryName: 'Marketing', scheduledAt: new Date('2025-12-25T00:00:00Z'), }); ``` ### `SendEmailOptions` type shape ```typescript theme={null} type SendEmailOptions = { userIds: string[]; // users to send to themeId?: string | null | false; // theme override subject?: string; // subject line notificationCategoryName?: string; // preference category html?: string; // raw HTML body templateId?: string; // template ID variables?: RecordHello!
', subject: 'Test Email', }); if (result.status === 'error') { switch (result.error.code) { case 'REQUIRES_CUSTOM_EMAIL_SERVER': console.error('Please configure a custom email server'); break; case 'SCHEMA_ERROR': console.error('Invalid email data provided'); break; case 'USER_ID_DOES_NOT_EXIST': console.error('One or more user IDs do not exist'); break; } } ``` ## Scheduling Pass a `scheduledAt` date to delay delivery. The email enters the pipeline immediately but won't be sent until the scheduled time. ```typescript theme={null} await hexclaveServerApp.sendEmail({ userIds: ['user-id'], html: 'Happy New Year!
', subject: 'Happy New Year!', scheduledAt: new Date('2026-01-01T00:00:00Z'), }); ``` If `scheduledAt` is omitted, the email is sent as soon as possible. ## Email pipeline Emails are processed asynchronously through a multi-stage pipeline: 1. **Enqueue** - The email is saved to the outbox with its template, recipients, and scheduling metadata. 2. **Render** - The template TSX is compiled into HTML, subject, and plain text. 3. **Queue** - Rendered emails whose scheduled time has passed are queued for delivery, respecting your project's sending capacity. 4. **Send** - Emails are delivered, honoring notification preferences and skipping users who have unsubscribed. 5. **Track** - Delivery events (sent, opened, clicked, bounced, marked as spam) are recorded. You can monitor every email's status in the dashboard under **Emails → Sent**. ## Templates Templates are React Email components written in TSX. Each template receives the current `user`, `project`, and any custom `variables` you pass when sending. ```tsx theme={null} import { type } from "arktype"; import { Container } from "@react-email/components"; import { Subject, NotificationCategory, Props } from "@hexclave/emails"; export const variablesSchema = type({ featureName: "string", }); export function EmailTemplate({ user, project, variables, }: PropsHi {user.displayName}, check out {variables.featureName}!
Check out our new feature!
', subject: 'Product Updates', notificationCategoryName: 'Marketing', }); ``` If a user has unsubscribed from Marketing emails, the email will be automatically skipped during delivery. Marketing emails always include an unsubscribe link. ## React components integration Emails integrate with Hexclave UI components automatically (for example verification, password reset, and magic-link flows).\ For custom flows, trigger `sendEmail` from your server code: ```typescript theme={null} import { hexclaveServerApp } from '@hexclave/next'; // replace `next` with the correct framework SDK package export async function inviteUser(userId: string) { const result = await hexclaveServerApp.sendEmail({ userIds: [userId], templateId: 'invitation-template', subject: "You're invited!", variables: { inviteUrl: 'https://yourapp.com/invite/token123', }, }); return result; } ``` ## Email server configuration Configure your email server in the dashboard under **Emails → Email Settings**. There are four options: ### Shared (development only) The default for new projects. Emails are sent from `noreply@sent-with-hexclave.com` using Hexclave's shared infrastructure. Good for development - not suitable for production. ### Custom SMTP Connect any SMTP provider. Configure: * **Host** - e.g. `smtp.sendgrid.net` * **Port** - typically 587 (STARTTLS) or 465 (implicit TLS) * **Username** and **Password** * **Sender email** and **Sender name** ### Resend Connect your [Resend](https://resend.com) account by entering your API key. Hexclave configures the SMTP connection automatically. ### Managed Let Hexclave manage your email domain. Hexclave handles DNS configuration and deliverability for you. Set up requires: 1. Choose a subdomain (e.g. `mail.yourapp.com`) 2. Add the DNS records Hexclave provides 3. Verify the domain in the dashboardAvailable Credits
{credits.nonNegativeQuantity}
{permission ? 'You have the read permission' : 'You shall not pass'}
);
}
```
{permission ? 'You have the read permission' : 'You shall not pass'}
);
}
```
{permissions.map(permission => (
);
}
```
{permission.id}
))}
{permissions.map(permission => (
);
}
```
{permission.id}
))}
{permission ? 'You can access the admin dashboard' : 'Access denied'}
);
}
```
{permission ? 'You can access the admin dashboard' : 'Access denied'}
);
}
```
{permissions.map(permission => (
);
}
```
{permission.id}
))}
{permissions.map(permission => (
);
}
```
{permission.id}
))}
Team not found
;
}
const hasPermission = user.usePermission(team, '$invite_members');
if (!hasPermission) {
return No permission
;
}
// Perform corresponding action like inviting a user
```
### Team profile
A user can have a different profile for each team they belong to (Note this is different to the user's personal profile). This profile contains information like `displayName` and `profileImageUrl`. The team profile can be left empty and it will automatically take the user's personal profile information.
The team profile is visible to all the other users in the team that have the `$read_members` permission.
## Retrieving a user's teams
You can list all teams a user belongs to using the `listTeams` or `useTeams` functions or fetch a specific team with `getTeam` or `useTeam`. These functions work on both clients and servers.
{allTeams.map(team => (
{team.displayName}
))}
{someTeam ? someTeam.displayName : 'Not a member of this team'}
);
```
{allTeams.map(team => (
{team.displayName}
))}
{someTeam ? someTeam.displayName : 'Not a member of this team'}
```
{users.map(user => (
);
```
{user.teamProfile.displayName}
))}
{users.map(user => (
);
```
{user.teamProfile.displayName}
))}
Team not found
;
}
return (
Team Name: {team.displayName}
You are a member of this team.
{selectedTeam &&
}
);
}
```
Now, if you navigate to `http://localhost:3000/team`, you should be able to see and interact with the teams.
# Webhooks
Source: https://docs.hexclave.com/guides/apps/webhooks/overview
Receive real-time updates when events occur in your Stack project
Webhooks are a powerful way to keep your backend in sync with Stack. They allow you to receive real-time updates when events occur in your Stack project, such as when a user or team is created, updated, or deleted.
For payload schemas and each webhook event, see the [webhook API reference](/api/webhooks/users/usercreated).
## Setting up webhooks
In the Stack dashboard, you can create a webhook endpoint in the "Webhooks" section. After creating this endpoint with your server URL, you will start receiving POST requests with a JSON payload at that endpoint. The event payload will look something like this:
```json theme={null}
{
"type": "team.created",
"data": {
"id": "2209422a-eef7-4668-967d-be79409972c5",
"display_name": "My Team",
...
}
}
```
## Testing webhooks locally
You can use services like [Svix Playground](https://www.svix.com/play/) or [Webhook.site](https://webhook.site/) to test the receiving of webhooks or relay them to your local development environment.
## Verifying webhooks
To ensure the webhook is coming from Stack (and not from a malicious actor) and is not prone to replay attacks, you should verify the request.
Stack signs the webhook payload with a secret key that you can find in the endpoint details on the dashboard. You can verify the signature using the Svix client library. Check out the [Svix documentation](https://docs.svix.com/receiving/verifying-payloads/how) for instructions on how to verify the signature in JavaScript, Python, Ruby, and other languages. Here are example handlers across the supported frameworks:
All Teams
{teams.map(team => ( ))}Setting up with AI? Use this single prompt:
Choose your tech stack
Choose all that apply.
Filter:
Frontend
Backend
Database
Other
Select a tool to show setup instructions.
Loading...
;
}
```
Loading...
: data.length === 0 ?No notes found
: data.map((note) =>
{user ? (
<>
);
}
```
You are signed in
User ID: {user.id}
) : ( )}Supabase data
- {listContent}
Hello, {user.displayName ?? user.primaryEmail ?? "anon"}
;
} else {
return You are not logged in
;
}
}
```
{`Hello, ${user.displayName ?? user.primaryEmail ?? "anon"}`}
;
}
```
Current plan: {plan}
;
}
```
{user ? (
);
}
```
```tsx my-client-component.tsx theme={null}
"use client";
import { hexclaveClientApp, UserButton } from "../src/stack/client";
export default function MyClientComponent() {
const user = hexclaveClientApp.useUser();
const app = hexclaveClientApp.useHexclaveApp();
return (
Welcome, {user.displayName ?? "unnamed user"}
Your e-mail: {user.primaryEmail}
You are not logged in
{user ? (
);
}
```
Welcome, {user.displayName ?? "unnamed user"}
Your e-mail: {user.primaryEmail}
You are not logged in
Your user ID: {user.id}
;
}
```
Your email is {user.email}
;
}
// myFunctions.ts
export const myQuery = query({
handler: async (ctx, args) => {
// In queries & mutations, use the special `getPartialUser` function to get user info
const obj = await hexclaveServerApp.getPartialUser({ from: "convex", ctx });
return JSON.stringify(obj);
},
});
```
You can find the production-ready template with Stack-Auth, Convex & Shadcn pre-configured [here on GitHub](https://github.com/developing-gamer/next-convex-stack-template).
# Supabase
Source: https://docs.hexclave.com/guides/integrations/supabase/overview
Integrate Hexclave with Supabase RLS
This guide shows how to integrate Hexclave with Supabase row level security (RLS).
Loading...
: data.length === 0 ?No notes found
: data.map((note) =>
{
user ?
<>
)
}
```
Now you should be able to compare the data you can view with an anonymous user, an authenticated user. You can also add your user Id to the row 3 of the Supabase table, and you should be able to see the row if and only if you are signed in with that user.
You are signed in
User ID: {user.id}
: }Supabase data
- {listContent}
Signed in as {user.primaryEmail}
;
}
```
Routes that use browser redirects should render on the client:
```tsx title="src/routes/protected.tsx" theme={null}
import { useUser } from "@hexclave/tanstack-start";
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/protected")({
ssr: false,
component: ProtectedPage,
});
function ProtectedPage() {
const user = useUser({ or: "redirect" });
return Welcome, {user.primaryEmail}
;
}
```
You are not signed in.
; } returnHello, {user.displayName ?? user.primaryEmail ?? user.id}
; } ```Hello, {user.displayName ?? user.primaryEmail ?? user.id}
; } ```Please sign in.
; } returnHello, {user.displayName ?? user.primaryEmail ?? user.id}
; } ```Hello, {user.displayName ?? user.primaryEmail ?? user.id}
; } ```You are not a member of this team.
; } return (You are not a member of this team.
; } return ({team.displayName}
Team ID: {team.id}
All teams-
{teams.map((team) => (
- {team.displayName} ))}
-
{teams.map((team) => (
- {team.displayName} ))}
Workspace not found.
; } const canExport = await user.getPermission(team, "export_reports"); if (!canExport) { returnYou do not have access to exports in this workspace.
; } return ; } ```Workspace not found.
; } return-
{invitations.map((inv) => (
- {inv.teamDisplayName} - {inv.recipientEmail} ))}
Dashboard
; } ```Agent-first setup
Set up with one prompt.
Copy the full Hexclave setup prompt into your coding agent, or follow the manual instructions.
Navigate Through Our Docs
Start at the top and work your way down, or jump straight to the section you need.
Recommended Order
First-time setup, install the SDK, get auth running in minutes.
Compare development flows, configure your project, and use lower-level interfaces where needed.
Use hooks, objects, and types to read and write auth data directly in your app code.
Integrate Hexclave from any backend or language through HTTP endpoints and webhook flows.
Resources
Reach for product access, source code, and support channels when you need more than reference docs.
Not signed in
;
}
return Hello, {user.displayName}
;
}
```
## Related
* [StackApp object reference](/sdk/objects/hexclave-app)
* [User type reference](/sdk/types/user)
# StackApp
Source: https://docs.hexclave.com/sdk/objects/hexclave-app
Reference documentation for HexclaveClientApp and HexclaveServerApp objects.
This is a detailed reference for the `StackApp` object. For setup instructions, see [Setup](/guides/getting-started/setup).
## Overview
* [HexclaveClientApp](#stackclientapp) - Client-level permissions for frontend code
* [HexclaveServerApp](#stackserverapp) - Server-level permissions with full access
***
# HexclaveClientApp
A `StackApp` with client-level permissions. It contains most of the useful methods and hooks for your client-side code.
Most commonly you get an instance of `HexclaveClientApp` by calling [`useHexclaveApp()`](/sdk/hooks/use-hexclave-app) in a Client Component.
## Table of Contents
```typescript theme={null}
type HexclaveClientApp = {
new(options): HexclaveClientApp;
getUser([options]): PromiseHello, {user.name}
: Not signed in
;
}
```
```tsx theme={null}
"use client";
function MyProtectedComponent() {
useUser({ or: "redirect" });
return You can only see this if you are authenticated
;
}
```
Welcome!
Thanks for joining us.
", }); if (htmlResult.status === "error") { console.error("Failed to send email:", htmlResult.error); } ``` ```typescript theme={null} const templateResult = await hexclaveServerApp.sendEmail({ userIds: ["user-1"], templateId: "welcome-template", variables: { userName: "John Doe", activationUrl: "https://app.com/activate/token123", }, }); ```Token: {result.data.accessToken}
;
}
return No Google token available
;
}
```
{billing.defaultPaymentMethod
? `Card ending in ${billing.defaultPaymentMethod.last4}`
: "No payment method on file"}
);
}
```
Available Credits
{credits.nonNegativeQuantity}
{credits.displayName}
Welcome
Thanks for signing up!
", }); ```