Skip to content
Skills Library
Programming · Tool integration

identify

/identify

Use when the developer wants Opem to know who the signed-in user is: Opem.identify and Opem.reset, unverified people in the inbox, HMAC signing, the verification secret (vs_), the Require signed identities and Trust unsigned roles switches, roles and signedAt, the errors identity_required, identity_signature_required or identity_signature_invalid, or a signing sample in Node.js, Python, Ruby, PHP, Go, C# or Java.

Licence
MIT
Last repository change
10.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/check-signature.mjs

What it does and when to use it

Use when the developer wants Opem to know who the signed-in user is: Opem.identify and Opem.reset, unverified people in the inbox, HMAC signing, the verification secret (vs_), the Require signed identities and Trust unsigned roles switches, roles and signedAt, the errors identity_required, identity_signature_required or identity_signature_invalid, or a signing sample in Node.js, Python, Ruby, PHP, Go, C# or Java.

Original author description

Use when the developer wants Opem to know who the signed-in user is: Opem.identify and Opem.reset, unverified people in the inbox, HMAC signing, the verification secret (vs_), the Require signed identities and Trust unsigned roles switches, roles and signedAt, the errors identity_required, identity_signature_required or identity_signature_invalid, or a signing sample in Node.js, Python, Ruby, PHP, Go, C# or Java.

How it works

  1. First: is Opem connected?
  2. Stop at the chosen step
  3. Step 1: the browser call
  4. Step 2: harden, when Opem should trust the id
  5. Without the connection
  6. Roles
  7. Common mistakes
  8. References
Original SKILL.md headings · 74 lines, 1,617 words
SKILL.md preview
---
name: identify
description: "Use when the developer wants Opem to know who the signed-in user is: Opem.identify and Opem.reset, unverified people in the inbox, HMAC signing, the verification secret (vs_), the Require signed identities and Trust unsigned roles switches, roles and signedAt, the errors identity_required, identity_signature_required or identity_signature_invalid, or a signing sample in Node.js, Python, Ruby, PHP, Go, C# or Java."
---

# Tell the widget who the person is

After the person signs in to the developer's app, the page calls `Opem.identify()` with the app's own id for them and, if known, their email and name. Opem then keeps one record per id in the project, so the person sees the same requests on every device. That one browser call is all a first install needs, on every plan. Anyone can type `Opem.identify()` into a console, though, so Opem marks an unsigned person unverified, and trusts an identity only when the developer's server has signed it with the project's verification secret.

## First: is Opem connected?

Look for the Opem tools (`whoami`, `list_projects`). If the only Opem tool is `authenticate`, call it now and wait for the developer to sign in and consent; then call `whoami`. Only when the server cannot be connected, follow the dashboard path below.

## Stop at the chosen step

Do the steps the developer chose (their answers to the how-far questions the `onboard` and `install` skills ask, or what they asked for) and no further. When the next step would add a dependency, a file to the repository, a key, a workflow or a switch they did not ask for, name it as the next offer and stop. If nothing has been chosen yet, ask before the first such step.

## Step 1: the browser call

1. **Identify after sign-in:** call `Opem.identify({ id, email, name })` once the widget has loaded and the person is signed in, with the app's own stable id for them. Call `Opem.reset()` when they sign out. The browser sample is in [signing.md](references/signing.md).
2. **No server needed yet:** this works on every plan while the project's "Require signed identities" switch is off, which is the default for a new project (projects that were on a paid plan when signing became optional have it on). `list_projects` gives each project's switch as `requireIdentityVerification`; read it before promising the browser call alone is enough. The inbox marks those people unverified, and an unverified call never changes the email or name Opem has stored for the person.
3. **Check:** load a page signed in and open the widget's Your requests tab; the person's requests are theirs on any device. A refused identity shows `[Opem] The identity passed to identify() was refused (<code>)` in the console and the widget carries on as an anonymous visitor where the project allows them. The three codes are in [errors.md](references/errors.md).

## Step 2: harden, when Opem should trust the id

An unsigned id can be forged: anyone who knows a person's id could read their requests from the browser. When that matters, sign on the server and then switch signing on. This step adds a secret, server code and a switch, so take it only when the developer chose signed identities; after step 1 alone, name it as the next offer and stop.

- **Where the signature is made:** on the server, never in the browser. The verification secret starts with `vs_`. It belongs in the server's environment (`OPEM_VERIFICATION_SECRET`), never in code, the repository or a chat.
- **What is signed:** HMAC-SHA256 over the id, a newline and the email in lower case (nothing after the newline without an email). Lowercase hex. [canonical-string.md](references/canonical-string.md) has the exact string and worked examples.
- **A signature that is sent must be right,** whatever the switch says: a wrong one is refused with `identity_signature_invalid`.

1. **The verification secret:** `create_key` for a verification secret, which needs the connection's `keys` permission (without it the tool answers `forbidden`). The value is in the result once: write it to the server's git-ignored environment file as `OPEM_VERIFICATION_SECRET` in the same step and never echo it.
2. **Server:** add a signing function with `signIdentity` from `@opem/node`, or the sample for the server's language in [signing.md](references/signing.md). Read the secret from the environment. Return `signature` to the page, for example as data rendered into the HTML or from an endpoint only signed-in users can call.
3. **Browser:** pass it on: `Opem.identify({ id, email, name, signature })`. Those people are verified in the inbox from their next call.
4. **Switch it on:** once every signed-in page sends a signature, `set_identity_verification` with `required: true` turns on "Require signed identities", on any plan. From then on an unsigned identity is refused with `identity_signature_required`, so turn it on only after the signing is live. [verification-toggle.md](references/verification-toggle.md) has what each setting does.
5. **Prove the signing code** with the known-answer vectors before blaming the secret:

   ```sh
   node scripts/check-signature.mjs --vectors
   OPEM_VERIFICATION_SECRET=vs_test_secret node scripts/check-signature.mjs user-1 Jane@Example.COM owner,billing 1793318400
   ```

   (In Claude Code the script is at `${CLAUDE_SKILL_DIR}/scripts/check-signature.mjs`.) The second form prints the canonical string and the signature for any inputs, so the developer can compare their server's output line by line. It reads the secret from the environment, never from the command line; with the real secret, export it in the developer's shell or run the script from the server's environment rather than typing it into a command.

## Without the connection

When the MCP server cannot be connected, the project's Configuration page, Identity tab, in the dashboard holds the "Require signed identities" switch (every plan, off by default for a new project) and the verification secret (`vs_`, shown once, with Rotate). Step 1 needs neither. For step 2 the developer creates the secret there and copies it into the server's environment file themselves, never into the chat, and turns the switch on there once the signing is live. The rest is the same.

## Roles

**Roles are a Professional and Enterprise feature.** Before suggesting roles at all, or writing any roles code, read `get_plan`'s `accessByRole`, true on Professional and Enterprise (without the connection, the plan on the dashboard's Billing page). On Free and Basic the page may send roles, but they open no document, signed or not: signed roles are kept on the person for staff to see, unsigned roles are dropped before anything is stored, and the browser console says once `[Opem] roles were ignored: roles come with the Professional and Enterprise plans; the project's plan does not include them.` The "Trust unsigned roles" switch is not offered there (the Identity tab reads "Roles sent with an identity count on Professional and Enterprise."), and `set_identity_verification` with `trustUnsignedRoles: true` answers `403` `plan_limit_reached`. On those plans, say that roles come with Professional and Enterprise, and stop.

On Professional and Enterprise, roles decide which of the developer's documents the assistant may read for the person (the `knowledge-sync` skill tags them), and staff see them on the person's card in the inbox. There are two ways to send them.

**Signed (the default, and the safe one).**

- Send `roles` with `signedAt` (unix seconds) and sign both: `Opem.identify({ id, email, name, roles, signedAt, signature })`. With roles the signed string gains two lines, the roles sorted and comma-joined, then `signedAt` ([canonical-string.md](references/canonical-string.md)).
- **Signed roles lapse a day after `signedAt`,** so sign on each page render, not once at sign-in. The call stays verified and reads as a person with no roles until the page signs again. An identity without roles has no `signedAt` and does not lapse.

**Unsigned, with "Trust unsigned roles" on.** For an app with no server to sign on, or while the developer accepts the risk: `Opem.identify({ id, email, name, roles })`, no `signedAt` and no `signature`.

- **What they open:** with the project's "Trust unsigned roles" switch on, the roles are kept on the person, shown in the inbox as "Unverified", and open the documents tagged for them, exactly as signed roles do. They need no `signedAt` and do not lapse.
- **The risk, said plainly to the developer before switching it on:** anyone who has the publishable key (it is in every page) can call `Opem.identify()` from a browser console with any role and read every document tagged for that role. Use it only for documents the developer would not mind such a person reading; sign the identity when that matters.
- **Switching it on** (Professional and Enterprise; on Free and Basic the answer is `plan_limit_reached`): connected, `set_identity_verification` with `trustUnsignedRoles: true` (it leaves "Require signed identities" as it is; `required` and `trustUnsignedRoles` can be sent together). Without the connection, the Identity tab of the project's Configuration page has the switch under "Require signed identities". It cannot be switched on while "Require signed identities" is on, since no unsigned identity is accepted then. `list_projects` gives each project's `trustUnsignedRoles` beside `requireIdentityVerification`, and `get_widget_settings` gives both as `identity.trustUnsignedRoles` and `identity.required`.
- **With the switch off** (the default) on Professional and Enterprise, an unsigned identity with roles is still accepted as the person, unverified, with the roles dropped, and the browser console says once: `[Opem] roles were ignored: the project does not trust unsigned roles. Sign the identity, or switch Trust unsigned roles on.`

## Common mistakes

Signing in the browser; lower-casing the email on one side only; sorting roles on one side only; signing `roles` without `signedAt` (the console says `signedAt is needed with a signature when roles are sent`); a server clock more than five minutes fast; a rotated secret still in an old environment; switching "Require signed identities" on before every page sends a signature; sending unsigned roles and expecting them to count while "Trust unsigned roles" is off; writing roles code on Free or Basic, where no role opens a document.

## References

- [signing.md](references/signing.md): passing the identity from the browser, and signing it in Node.js, Python, Ruby, PHP, Go, C# and Java
- [canonical-string.md](references/canonical-string.md): the exact string that is signed, with worked examples
- [verification-toggle.md](references/verification-toggle.md): the "Require signed identities" and "Trust unsigned roles" switches, off and on
- [errors.md](references/errors.md): the three `identity_*` error codes and their causes
- [identity-vectors.json](references/identity-vectors.json): known-answer test vectors for the signature
Files in this package (7)
  • SKILL.md 11 KB
  • references/canonical-string.md 2 KB
  • references/errors.md 1 KB
  • references/identity-vectors.json 1 KB
  • references/signing.md 6 KB
  • references/verification-toggle.md 4 KB
  • scripts/check-signature.mjs 3 KB

Versions

The database has no other skills named identify.

Database snapshot: 13.11.2026 · package version 84f281f4e72f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90onboard
    Use when the developer has no Opem account or project yet, asks how to start with Opem, or holds a key (pk_, sk_, vs_) with no idea where it goes. Walks through signing up at support.opem.app, creating a project, and finding the publishable key, the allowed origins and the…
  • 100webhooks
    Use when the developer wants their server told when a request is raised, replied to or closed, or when the assistant answers: Opem webhooks, verifyWebhook from @opem/node, the Opem-Signature header, the whsec_ secret, redelivery, or testing a webhook handler locally.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.