# Auth.md

NewLedger supports two authentication patterns for integrations and AI agents:

- API credentials for server-to-server integrations you operate.
- OAuth 2.0 with PKCE for delegated clients that need a signed-in user to approve access.

This site is a public discovery and documentation origin. It does not publish client secrets, company-specific MCP URLs, or tenant-scoped connection details. The production API gateway is [api.newledger.io](https://api.newledger.io/), and browser sign-in, workspace selection, consent, and revocation happen in the NewLedger web app at [app.newledger.io](https://app.newledger.io/).

## Use this document for

- Discovering the public NewLedger API and integration docs.
- Choosing the right authentication pattern before implementation.
- Understanding which steps require sign-in, user approval, and 2FA.

## Server-to-server integrations

Use this path when your backend, worker, ETL job, or partner service connects directly to NewLedger and can store a secret safely.

1. Sign in to [app.newledger.io](https://app.newledger.io/).
2. Open **Settings -> App Connect -> API Credentials**.
3. Create an app, delegate the minimum permissions it needs, and copy the `client_id` and `client_secret`.
4. Exchange those credentials for short-lived bearer tokens from your backend.
5. Call the API gateway at [api.newledger.io](https://api.newledger.io/) using the endpoints described by the [OpenAPI spec](https://newledger.io/openapi.json).

Operational notes:

- Keep `client_secret` values in a vault or secrets manager.
- Rotate or revoke credentials from App Connect if ownership or scope changes.
- Use a test workspace before granting production access.

## Delegated OAuth clients and MCP assistants

Use this path when a signed-in user needs to approve access in the browser, including MCP-compatible assistants such as ChatGPT or Claude Desktop.

1. Sign in to [app.newledger.io](https://app.newledger.io/).
2. Open **Settings -> App Connect -> MCP Server** to copy the company-specific MCP URL, or register an OAuth client if your integration needs its own redirect URI.
3. Start the connection from the external client.
4. Complete the NewLedger consent flow, review scopes, and confirm with 2FA.
5. Manage or revoke the connection later from **Settings -> App Connect -> OAuth Connections**.

Operational notes:

- The REST API gateway is [api.newledger.io](https://api.newledger.io/).
- The web app for user consent and connection management is [app.newledger.io](https://app.newledger.io/).
- The MCP endpoint is workspace-specific rather than a single public server URL.
- Public clients should use OAuth 2.0 with PKCE.
- Scope approval should follow least-privilege principles.
- NewLedger's documented AI flows are consent-based, scoped, and reviewable.

## Agent registration boundaries

- This marketing site does not expose pre-consent tenant details for SaaS workspaces.
- OAuth setup requires a signed-in user, an approved workspace context, and explicit scope consent.
- Company-specific MCP URLs are disclosed only inside the NewLedger app after sign-in.
- If your integration needs partner onboarding or production enablement, coordinate through NewLedger rather than expecting anonymous self-service registration from this public site.
- The public OAuth registration endpoint is discoverable, but successful client registration still requires a signed-in workspace user and approved consent.

## Agent registration

Use this public flow when an AI agent, MCP client, or delegated integration needs to register for NewLedger access.

1. Read the [OAuth authorization server metadata](https://newledger.io/.well-known/oauth-authorization-server) and its `agent_auth` object.
2. Register through the `register_uri` shown below.
3. Use one of the `supported_credential_types`; browser-based agents should use `oauth2_authorization_code_pkce`.
4. Send the user to the `authorization_uri` with the requested least-privilege scopes.
5. Complete consent, workspace selection, and 2FA in the signed-in NewLedger web app.
6. Exchange the authorization code at the `token_uri`.
7. Store issued credentials securely and call the API gateway or company-specific MCP endpoint only within the approved scopes.
8. Revoke access later through the `revocation_uri` or **Settings -> App Connect -> OAuth Connections**.

```json
{
  "agent_auth": {
    "skill": "https://newledger.io/.well-known/agent-skills/newledger-auth/SKILL.md",
    "skill_url": "https://newledger.io/.well-known/agent-skills/newledger-auth/SKILL.md",
    "register_uri": "https://connect.newledger.io/v1/app-connect/oauth/register",
    "authorization_uri": "https://app.newledger.io/oauth/authorize",
    "token_uri": "https://connect.newledger.io/v1/app-connect/oauth/token",
    "revocation_uri": "https://app.newledger.io/settings/app-connect/oauth-connections",
    "supported_identity_types": ["signed-in-workspace-user", "delegated-mcp-client"],
    "supported_credential_types": ["oauth2_authorization_code_pkce"],
    "claims_uri": "https://newledger.io/.well-known/agent-skills/newledger-auth/SKILL.md#agent-registration-claims",
    "workspace_required": true,
    "consent_required": true,
    "resource_servers": ["https://api.newledger.io/v1"],
    "oauth_service": "https://connect.newledger.io/v1/mcp",
    "web_application": "https://app.newledger.io"
  }
}
```

### Agent registration claims

- `identity_type`: `signed-in-workspace-user` or `delegated-mcp-client`.
- `credential_type`: `oauth2_authorization_code_pkce`.
- `workspace_required`: `true`.
- `consent_required`: `true`.
- `scopes`: use the least-privilege values listed in the authorization server metadata.

## Revocation

Users can revoke delegated agent, OAuth, and MCP connections from [the NewLedger app](https://app.newledger.io/settings/app-connect/oauth-connections) under **Settings -> App Connect -> OAuth Connections**.

## Discovery metadata

- OAuth authorization server metadata: [https://newledger.io/.well-known/oauth-authorization-server](https://newledger.io/.well-known/oauth-authorization-server)
- OAuth protected resource metadata: [https://newledger.io/.well-known/oauth-protected-resource](https://newledger.io/.well-known/oauth-protected-resource)
- MCP server card: [https://newledger.io/.well-known/mcp/server-card.json](https://newledger.io/.well-known/mcp/server-card.json)
- Public discovery resource: [https://newledger.io](https://newledger.io)
- Production API gateway: [https://api.newledger.io/v1](https://api.newledger.io/v1)
- OpenAPI server base URL: [https://api.newledger.io](https://api.newledger.io)
- Web app and consent UI: [https://app.newledger.io](https://app.newledger.io)
- Public discovery issuer: [https://newledger.io](https://newledger.io)
- OAuth service for delegated MCP access: [https://connect.newledger.io/v1/mcp](https://connect.newledger.io/v1/mcp)
- Browser authorization UI: [https://app.newledger.io/oauth/authorize](https://app.newledger.io/oauth/authorize)

The metadata files above are the public discovery copies hosted on this marketing site. They use [newledger.io](https://newledger.io/) as the public discovery issuer so agent-readiness validators can resolve same-origin metadata. The backend OAuth and MCP service remains [connect.newledger.io](https://connect.newledger.io/v1/mcp), and the protected resource metadata identifies [api.newledger.io](https://api.newledger.io/) as the production API gateway.

## Discovery and documentation

- API catalog: [https://newledger.io/.well-known/api-catalog](https://newledger.io/.well-known/api-catalog)
- OpenAPI spec: [https://newledger.io/openapi.json](https://newledger.io/openapi.json)
- API reference UI: [https://newledger.io/api-documentation](https://newledger.io/api-documentation)
- Agent skills index: [https://newledger.io/.well-known/agent-skills/index.json](https://newledger.io/.well-known/agent-skills/index.json)
- Integration guidance: [https://newledger.io/blog/accounting-api-integration](https://newledger.io/blog/accounting-api-integration)
- MCP product overview: [https://newledger.io/blog/mcp-for-accounting](https://newledger.io/blog/mcp-for-accounting)

## Support

If you need partner onboarding, production rollout help, or clarification on scopes and registration, use [https://newledger.io/contact](https://newledger.io/contact).
