> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aveid.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Ave for Businesses

> Use Ave organizations as identity containers with roles, org context claims, audit trails, and explicit key boundaries.

Ave organizations let a person act with a specific Ave identity inside a company or team context. There is no company password and no shared company login. A business organization contains identities, roles, scopes, signing authority, key grants, verified domains, and SSO configuration.

If you are building a SaaS workspace integration where Ave manages members for your app, start with [Business workspaces](/guides/business-workspaces). This page covers the underlying business identity and security behavior.

## Organization context

Apps that support business context send an `organization_id` on the Ave authorize URL. Ave verifies that the selected identity is an active member of that organization before issuing tokens.

```ts theme={null}
import { buildAuthorizeUrl } from "@ave-id/sdk";

const url = buildAuthorizeUrl(
  { clientId: "YOUR_CLIENT_ID", redirectUri: "https://app.example.com/callback" },
  {
    scope: ["openid", "profile", "email", "offline_access"],
    organizationId: "org_...",
  }
);
```

When organization context is valid, the access token JWT and ID token include:

```json theme={null}
{
  "auth_context": "organization",
  "org_id": "org_...",
  "org_name": "Example Co",
  "org_member_id": "orgmem_...",
  "org_role": "admin",
  "org_scopes": ["read", "sign", "approve"],
  "org_signing_authority": true,
  "org_encryption_mode": "enterprise_managed",
  "org_key_custody": "customer_kms",
  "auth_method": "enterprise_sso",
  "sso_connection_id": "sso_..."
}
```

Use the normal `sub` claim as the stable Ave identity ID. Use `org_id` and `org_member_id` only for organization authorization decisions. When an organization requires SSO, Ave only issues or refreshes organization-context tokens from a session created by that organization's SSO connection.

## Signed organization actions

Business administration actions require an Ave identity signature from the acting organization identity. The business console signs organization creation, member add/remove/role changes, org key creation, domain verification, SSO setup, and SSO policy changes before sending them to the API.

The server verifies the signature against the canonical audit payload before applying the mutation. Audit events store the payload, verified signature, public key, and signature status.

The developer portal uses the same organization permissions. Member invitations and role changes require `manage_identities`, signing authority, and a signature from the acting identity. Administrators can manage members below their own role; they cannot restore their own permissions or change another administrator. Workspace name and logo changes require `manage_org` and signing authority, and profile updates are signed. App administration requires an administrator or owner with signing authority.

When SSO is required, opening organization member and app data or administering the organization in either console requires that organization's SSO session. An owner with signing authority retains recovery access.

Deleting an Ave account also deletes organizations it owns and their apps. Apps in another owner's organization remain with that organization when the account of their original creator is deleted.

## Encrypted org keys

Business organizations have an explicit encryption mode:

| Mode               | Behavior                                                                                                                                                   |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Standard           | Seamless org encryption tied to Ave access policy. This is not marketed as E2EE.                                                                           |
| Enterprise-managed | Stores a customer KMS key reference for AWS KMS, Azure Key Vault, Google Cloud KMS, or an external provider. Ave stores the reference, not a cloud secret. |
| E2EE               | Browser-generated org keys are stored only as per-identity wrapped grants. Members need Ave identity encryption keys before they can receive grants.       |

In E2EE mode, org keys are not plaintext server secrets. The business UI generates key material in the browser and stores only per-identity wrapped grants. A member can use an org key only when their Ave identity has a usable identity encryption key and a wrapped grant exists for that identity.

Identity encryption keys are separate from Ed25519 signing keys. Signing proves the acting identity approved an organization action; encryption grants control who can unwrap org key material.

Enterprise SSO does not grant encrypted key access by itself. SSO can authenticate a company user, but encrypted data access still requires Ave identity key grants.

When an enterprise SSO login succeeds, the provider email must belong to the connection's exact DNS-verified organization domain. Ave then links an existing Ave identity with that email or creates a limited SSO identity. Newly provisioned SSO identities can access normal organization context, but they do not receive encrypted org keys until an Ave identity encryption key exists and a grant is issued.

SSO does not reactivate suspended or removed organization memberships. An authorized administrator must restore membership before that identity can sign in to the organization again.

Removing an identity from an organization revokes its active org-key grants. For hard revocation, rotate the org key: Ave creates a new key epoch and rewraps access only for the remaining active identities. Data already decrypted on a device cannot be erased retroactively.

## SSO setup status

Business organizations can save SAML/OIDC connection configuration and generate SAML service provider metadata. Domain verification uses a DNS TXT record at:

```txt theme={null}
_ave-challenge.example.com TXT ave-domain-verification=...
```

Every OIDC or SAML connection requires a domain verified through this DNS challenge. Listing a domain in workspace profile data does not verify it. Ave checks the domain verification record when configuring a connection, starting SSO, testing it, and completing sign-in.

OIDC and SAML connections can be tested from the business console by an administrator with `manage_sso` and signing authority. A successful callback for the verified domain activates the connection. Only active connections with a current domain verification can satisfy SSO enforcement.

SAML assertion login validates the posted response signature against the stored IdP certificate, then checks issuer, audience, recipient, expiration, and email domain before creating an enterprise SSO session. The SSO endpoints do not claim E2EE support, and apps should not treat SSO as an encrypted key delivery path.