> ## Documentation Index > Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code. > Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer. > For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them. > The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes. # Harden your organization > Security defaults and recommended settings for organization Owners and Admins, and where to change each one. > [!WARNING] > > **Beta is a preview.** The Beta (2.0) platform does not have all the features > of [Stable](https://docs.photon.codes/docs/spectrum-ts/introduction.md) yet. For example, iMessage on Beta > supports only text and images, so tapbacks, polls, message effects, and voice > notes are [only on Stable](https://docs.photon.codes/docs/spectrum-ts/providers/imessage/messaging-features.md) > for now. Use Stable for production agents, and confirm that Beta supports the > features you need before you buy a plan. Photon is secure by default. Your organization's data is never shared publicly, only Owners and Admins can invite people, and every credential is scoped and shown only once. This page lists each security control, its default, and what we recommend for production. Work through it when you set up an organization, and again each time you review access. ## What Photon handles and what you configure | Photon | You | | - | - | | Authenticates every Dashboard session and API request, and checks the caller's role or credential permissions each time. | Decide who joins your organization and which role they get. | | Keeps organization and project data visible only to your members and to the credentials you issue. | Give each credential only the access its integration needs, and revoke it when the integration is retired. | | Requires single sign-on for every member once your identity provider is connected. | Connect your identity provider and manage who's assigned to Photon in it. | | Signs every webhook delivery, sends it only over HTTPS, and refuses private network destinations. | Verify signatures on your server and keep signing secrets out of your code. | ## Checklist | Control | Default | Recommended | | - | - | - | | [Single sign-on](#sign-in) | Off | Connect your identity provider. | | [Two-factor authentication](#sign-in) | Off for each account | Every member turns it on, if you don't use single sign-on. | | [Who can invite](#roles-and-invitations) | Owners and Admins only | Keep this to a few Admins, and at least one besides the Owner. | | [Role for new members](#roles-and-invitations) | **Can view** | Give **Can edit** only to people who change projects. | | [Automatic joining](#roles-and-invitations) | Off | Leave it off unless everyone in your identity provider should see your projects. | | [Pending invitations](#roles-and-invitations) | Expire after 7 days | Revoke the ones you no longer need. | | [Offboarding](#offboarding) | — | Remove people from **Members**, not only from your identity provider. | | [Project API keys](#credentials) | Expire after 90 days when created in the Dashboard | Choose the narrowest permissions and keep an expiry. | | [Account service keys](#credentials) | Expire after 90 days when created in the Dashboard | Use project API keys or service identities instead where you can. | | [Apps](#apps-and-connectors) | Installed by Owners and Admins only | Give each App only the projects it needs. | | [Connectors](#apps-and-connectors) | Each person approves their own | Revoke the ones nobody uses. | | [Webhooks](#webhooks) | Signed, HTTPS only | Verify every delivery and rotate the signing secret if it leaks. | | [Public sharing](#data-exposure) | Not available | Nothing to turn off. | | [Photon support access](#photon-support-access) | See [Photon support access](https://docs.photon.codes/docs/beta/security/support-access.md) | — | ## Sign-in **Single sign-on.** Connect your identity provider in **Organization settings** > **Single sign-on**. As soon as it's connected, every member, including the Owner, must sign in through it. Your identity provider then applies your own password and multi-factor rules. See [Single sign-on](https://docs.photon.codes/docs/beta/sso.md) for setup. **Two-factor authentication.** Each person turns it on for their own account in **Account settings** > **Security** with an authenticator app. After that, signing in asks for a code from the app. Photon can't require two-factor authentication for a whole organization, so ask your members to turn it on, or use single sign-on and require multi-factor authentication in your identity provider. ## Roles and invitations Every member has one role, and it applies to every project in the organization. | Role | What it can do | | - | - | | Owner | Everything an Admin can do, plus manage Admins, transfer ownership, and delete the organization. Each organization has one Owner. | | Admin | Full access to projects, plus the organization's members, billing, 10DLC, single sign-on, service identities, and Apps. Can't manage other Admins. | | Can edit | Create, change, and delete projects, including their platforms and API keys. Can't invite people or manage billing. | | Can view | Read every project, including its messages, calls, platforms, and usage. Can't change anything. | > [!WARNING] > > **Can view** isn't a no-data role. It can read every project's messages and > call data. Invite only people who should see your conversations. **Who can invite.** Only Owners and Admins can invite people, remove members, and change roles. People with **Can edit** or **Can view** can't invite anyone. Admins can invite with **Can view** or **Can edit**, and only the Owner can make a member an Admin. Keep the number of Admins small, but have at least one besides the Owner, so someone can manage access when the Owner is unavailable. **Invitations.** Invite people in **Organization settings** > **Members**. New invitations default to **Can view**. An invitation expires after 7 days and grants nothing until it's accepted. Pending invitations are listed under **Invitations**, where you can revoke the ones you no longer need. **Automatic joining.** With single sign-on, you can let anyone who signs in through your identity provider join automatically as **Can view**. It's off by default. Turn it on only if everyone assigned to Photon in your identity provider should be able to read your projects. See [Let new people join automatically](https://docs.photon.codes/docs/beta/sso.md#let-new-people-join-automatically). ## Offboarding When someone leaves, remove them in **Organization settings** > **Members**: open **More actions** next to their name and select **Remove from organization**. Removing them ends their access to the organization right away. Deactivating someone in your identity provider stops them from signing in, but connectors and personal keys they already set up keep working until you remove them from **Members**. Project API keys and service identity credentials belong to the project or the organization, not to the person who created them. They keep working after that person leaves. Revoke and replace any key the person could copy. ## Credentials Choose the credential with the least access that does the job. See [Credentials](https://docs.photon.codes/docs/beta/api-client/credentials.md) for how each one works. | Credential | Scope | Use it for | | - | - | - | | Project API key | One project, with the permissions you choose | A service that works in one project. | | Service identity | Your organization, with the permissions you approve | Automation across several projects. | | Account service key | Everything your own account can do | Personal scripts that need your account's access. Don't share it. | * **Choose narrow permissions.** When you create a project API key, select **Read only** or **Event ingestion** if that's all the service needs, or **Custom** to pick permissions. You can narrow a key's permissions later without replacing it. * **Keep an expiry.** In the Dashboard, keys expire after 90 days unless you choose another lifetime. Through the API, a key expires only if you set `expiresAt`. Choose **No expiry** only for a key you rotate on your own schedule. * **Store secrets once.** Photon shows each secret only when it's created. Put it in your secret manager. Never commit it to source control or put it in browser or mobile code. * **Revoke what you don't use.** Revoke a key as soon as it's retired or might have leaked, then create a new one. ## Apps and connectors **Apps** are installed for the whole organization. Only Owners and Admins can install them, in **Organization settings** > **Apps**. When you install an App: * Review the permissions it asks for. If the App later asks for more, it doesn't get them until an Owner or Admin approves the update. * Under **Project access**, select only the projects the App needs. With **All projects**, the App also gets every project created later. * Use **Suspend access** to pause an App, or **Uninstall** to remove it. See [Permissions and lifecycle](https://docs.photon.codes/docs/beta/apps/permissions.md) for details. **Connectors** are apps and AI tools, such as MCP clients, that a person signs in to with their Photon account. A connector acts as that person, with only the access they approved. Each person reviews their own in **Account settings** > **Connectors**, and can revoke a connector's access there at any time. ## Webhooks * Verify the signature on every delivery, and reject requests that fail. See [Verify with Standard Webhooks](https://docs.photon.codes/docs/beta/message-delivery/webhook.md#verify-with-standard-webhooks). * Keep the signing secret in your secret manager. If it might have leaked, [rotate it](https://docs.photon.codes/docs/beta/api-client/sdk/projects/rotate-webhook-signing-secret.md). * If your receiver only accepts known senders, allow the egress addresses listed on your project's **Webhooks** page. Photon sends deliveries only to public HTTPS URLs, doesn't follow redirects, and refuses private network destinations such as `localhost`. ## Data exposure Photon has no public sharing. Projects, messages, attachments, and settings can be read only by your organization's members, by credentials you issue, and by Apps and connectors you approve. Attachments are downloaded through the authenticated API and are never exposed through public storage links. ## Photon support access Photon support can sign in as a specific account to troubleshoot a problem. See [Photon support access](https://docs.photon.codes/docs/beta/security/support-access.md) for how this works and what it can do. ## Review access regularly Every quarter, or when your team changes: 1. In **Members**, check each person and role, and revoke stale invitations. 2. In each project's **API keys**, revoke keys nobody uses and check the permissions of the rest. 3. In **Service identities**, revoke credentials nobody uses. 4. In **Apps**, check each App's permissions and project access. 5. Ask members to review their **Connectors** and **Service keys**. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.