# Core concepts

A relying party (RP) is an application registered with SecurySign. Its registration defines the application's credentials, permitted origins, redirect URLs, scopes and signing allowance. API operations use either those application credentials or an individual user's access token.

## Environments

Sandbox and production have separate registrations, credentials and tokens.

| Resource | Production | Sandbox |
|---|---|---|
| API | `https://securysign.com/api` | `https://signa.dev.securysign.com/api` |
| OpenID Connect (OIDC) issuer | `https://securysign.com/auth/realms/signa` | `https://idp.dev.securysign.com/realms/signa` |
| Signing iframe | `https://securysign.com/#/sign-frame` | `https://signa.dev.securysign.com/#/sign-frame` |
| MIMI enrolment | `https://mimi.ke` | SecurySign supplies a staging client on request. |

## Credentials

Application credentials belong on the backend. Requests that act on a signed-in user instead use the access token obtained by exchanging that user's authorization code.

| Credential | How you send it | Where you obtain it | Where you use it |
|---|---|---|---|
| RP client ID and OIDC client secret | `Authorization: Basic base64(client_id:client_secret)` | Your approved RP registration. | Identity verification and enrolment-reference requests. |
| Secure Signature Confirmation (SSC) secret | `clientSecret` in JSON. | The [RP dashboard](https://cloud.securysign.com/#/rp/dashboard), or `ssc_secret` from `GET /rp/me`. | `POST /ssc/token`. |
| User access token | `Authorization: Bearer <access_token>` | [Single sign-on](#/docs/sso). | Hash signing, PAdES signing, certificates, encryption, webhooks and RP self-service. |
| MIMI client credentials | HTTP Basic authentication at `https://mimi.ke/token`. | Your separate MIMI client registration. | The MIMI enrolment code exchange. |

For identity capture, the backend requests a liveness session or a phone handoff from SecurySign. A liveness token authorizes the capture component for one verification and expires after 600 seconds. A handoff link lets the customer complete that verification on their phone and expires after 900 seconds.

### Credential rules

Hash signing, PDF Advanced Electronic Signature (PAdES) signing and webhook requests require a signed-in user's bearer token. RP administration and webhook subscriptions belong to the contact account identified by `contact_email`; use that account for dashboard changes and RP self-service requests.

The SSC secret and OIDC client secret are distinct. Rotating credentials on the dashboard replaces the OIDC client secret. Contact SecurySign support to rotate the SSC secret.

The permanent account identifier in an OIDC token is `sub`. The `email` claim contains the address, and `email_verified` indicates whether the identity provider has verified it. Authorization requests must use scopes assigned to the client; requesting an unassigned scope produces `invalid_scope`.

## Scopes

Scopes determine which capabilities and claims an application receives. Request them during registration or through the RP dashboard; they take effect after approval.

| Scope | What you use it for |
|---|---|
| `signa:sign` | Identify your RP as a signing integration; the granted value appears in the user's token `scope` claim. |
| `signa:integrator` | Register an enterprise identity provider through the Integrations panel or API. |
| `signa-kyc` | Submit identity-verification requests. |
| `signa-enrolment` | Start hosted enrolment. |
| `signa-entitlement-required` | Require an active subscription during enrolment. |
| `signa-visible-signature` | Receive `visible_signature_url`, `visible_signature_id` and `visible_signature_sha256` claims. |
| `signa-certificate` | Receive `signa_certificate_url`, `signa_certificate_serial` and `signa_certificate_subject` claims. |

## Levels of assurance

Each signing token specifies a level of assurance (LOA), up to the RP's approved maximum. Registered signing defaults to `LOA-2`.

| Level | How the signing request is authorised |
|---|---|
| `LOA-0` | You use the anonymous demonstration flow. |
| `LOA-1` | You identify an authorised embedding origin in the anonymous flow. |
| `LOA-2` | Your backend supplies a signing token; the customer approves with a registered passkey. |
| `LOA-4` | Your token names the signer and is bound to the passkey selected for that signer. |

A `LOA-4` token request must include the signer's `email`. SecurySign binds the token to that account's most recently registered passkey. See [LOA-4 setup](#/docs/rp-integration-guide#5-enable-loa-4) for the RP verification and approval requirements.

## Terms

| Term | Meaning in your integration |
|---|---|
| RP | Your application registration, or the WebAuthn domain when discussing a passkey's RP ID. |
| SSC | Secure Signature Confirmation: the signing frame and its token-based approval flow. |
| Passkey | The WebAuthn credential your customer uses to approve an operation. |
| `sub` | The permanent OIDC account identifier you receive in tokens. |
| MIMI | The enrolment service at `mimi.ke`, reached through its OIDC authorization endpoint. |
| HSM | Hardware security module: the platform component that holds and uses the server-side cryptographic keys. |