Skip to main content
Call NoResponse first from the backend code that gives a new account something of value to an attacker. That is its free credits or its first API key. This page builds that gate in TypeScript, Python or Go. It works for an app that uses Clerk, WorkOS or Auth0 for login, or that has its own login. The gate does these things in order:
  1. Your backend verifies the session of the new account, and maps the verified claims to auth_context.
  2. It creates the API key of the account, inactive.
  3. It calls POST /v1/assessments with flow account_creation and the SHA-256 of the key.
  4. It applies the decision: block refuses, allow grants, step_up asks for a second factor and review holds the account.
1

Create a workspace

Create your workspace with your email address. One call creates it and immediately answers its test key. Thus you or your agent can start before anyone opens a mailbox.
Create a workspace
Response
To give the workspace a name, such as the name of your company, add workspace_name to the body: {"email":"you@example.com","workspace_name":"Acme"}. Without it, the workspace has no name until you give it one in the console.The test key starts with nrk_test_. NoResponse shows it once, so store it now. It carries the assess, history, delete, webhooks, integrations and groups scopes. assess covers every call on this page: it creates the assessment and polls it with wait.
A test key calls the same API as a live key, but a deterministic simulator answers it. NoResponse looks up no source and charges nothing. Magic emails such as step_up@test.noresponse.org and block@test.noresponse.org give each decision when you want it. Test your integration lists every magic identifier.
The data that you create with a test key stays in your test environment, separate from live data. You build this full page on the test key. In the last step you change to a live key (nrk_live_). Test and live environments explains the two environments.The live key comes from the email that we send to your address. Open its link, or post the token from it:
Claim the live key
The answer has status active and your live_key. NoResponse shows the live key once. Some workspace creations answer status held instead. We then examine the workspace, and email you a link that claims the live key after we approve it. Your test key works during this time.If our own assessment blocks the creation, it answers 403 workspace_refused and gives no key. While your verification link waits unopened, a second call for the same address answers 409 signup_pending and makes nothing. The link works for 24 hours. One address can create a workspace 3 times an hour.
If we invited your team to the console, you can create the workspace there:
  1. Open the invitation email and create your user with your work address.
  2. Enter your company name. The console makes the same call and shows the test key once.
  3. Create more keys on API keys. A live key is in the live environment.
2

Set your keys

Put your keys in the environment of your backend, next to the keys of your auth provider. Keep all of them out of browser and mobile code.
Environment
The NoResponse SDKs read NORESPONSE_API_KEY and call https://api.noresponse.org. You set nothing more for NoResponse.
To receive late answers by webhook later, ask for a second key with the webhooks scope. Keep it separate from this key. Webhooks shows how to use it.
3

Install the SDKs

Install the NoResponse SDK and the SDK of your auth provider. WorkOS and Auth0 sessions are JSON Web Tokens, so those tabs add a JWT library to verify them. With your own login, you install only the NoResponse SDK.
TypeScript
The NoResponse SDKs need Node.js 20, Python 3.10 or Go 1.24 or later. Of the provider packages, @workos-inc/node needs Node.js 22.11, the Go JWT module needs Go 1.25, and the Go Auth0 module needs Go 1.26.
4

Verify the session and map it

Your backend verifies the session with the SDK of your auth provider. Then it reads the user record for the facts that the token does not hold. The NoResponse adapter changes the verified claims and those facts into auth_context. NoResponse refuses raw tokens, so only verified claims leave your backend.The account id is the user id from your auth provider, sent without change. The gate looks up the email address of the account. Thus verifyNewAccount refuses a user without one.
Use the Clerk session token that your frontend sends. Clerk’s getToken() returns it. Send it in the Authorization: Bearer header.Replace https://app.example.com with the origin of your frontend. Clerk compares it with the azp claim of the token.
TypeScript
With an auth provider, the adapter reads these facts from the claims: the session id, organisation, roles, second factor and impersonation. Pass your auth session lists each field that each adapter maps, and the session facts that you can add.
5

Call NoResponse

Run this in the backend route that grants the credits or the first API key, before it grants them. From here, the code is the same for every auth provider and for your own login.
  1. Create the API key of the account and store it inactive.
  2. Send the SHA-256 of the key as issued_credential.sha256. The key never leaves your backend.
  3. Make the Idempotency-Key from the key id.
NoResponse stores the hash. Thus a key that shows up later in abuse or in a leak links back to this account creation. Because the Idempotency-Key comes from the key id, a retry of this call replays the same assessment. It does not start a new one.If your gate grants credits and no key, do not send issuedCredential. Make the Idempotency-Key from your own id for the grant. With your own login, newAccount.authContext is empty, and the SDK does not send auth_context.flow names the flow that you assess: account_creation here, login at login and purchase at purchase. The samples do not send depth. Thus account creation gets the default full, which waits up to 3,000 ms for the sources. quick waits only for the sources that answer within 500 ms. It is the default for login.In the samples:
  • token is the token from step 4: the Clerk session token, WorkOS access token, Auth0 ID token or your own session token.
  • clientIp is the address of the user, as your load balancer reports it.
  • apiKeys is your own key store.
ip must be a public address. The API refuses private, loopback and documentation addresses such as 192.0.2.1 with a 400. Thus a request from your own computer through localhost needs a real address in its place. The API accepts 81.2.69.160.
TypeScript
The answer starts with account, the one current risk of the account. It holds the score, the decision for this flow and the reasons for them. This is the part that you act on. The facts of this assessment alone are under detail, for example its status, confidence and incomplete sources.
Response
detail has more fields than shown here. The assessment describes each one.A 4xx answer raises a typed error in every SDK:
  • A 400 names the field that it refused in invalid_params.
  • A 401 means that the key is missing or revoked.
  • A 403 means that the key does not have the assess scope.
Errors lists each error.
6

Act on the answer

Act on account.risk.decision. Your code decides. NoResponse never blocks an account creation itself.Any decision that the SDK does not recognise goes to review. apiKeys, credits and reviewQueue are your own code.
TypeScript
Call act with the answer from step 5. When it returns pending, do these steps:
  1. Tell the user that you are setting up the account.
  2. In a background job, wait for the final answer.
  3. Call act again.
wait polls until the status of the assessment is complete. It polls at the interval that the Retry-After of the API gives, and at most once a second. It stops after a timeout, 30 seconds unless you set a different one.
  • If the answer is partial at the timeout, wait returns it with its status still partial. act then runs on its recommendation.
  • If the answer is still pending, wait raises a timeout error that carries the pending answer.
If you prefer not to poll, the account.risk_changed webhook delivers the final decision.
TypeScript
A timeout, a 429 or a 503 from NoResponse also has no decision. The SDKs retry those for up to 30 seconds, and then raise an error. Keep the key inactive. From a background job, retry assessments.create with the same key, the same body and the same Idempotency-Key.
Do not run the full gate again. That creates a second key and a second assessment.
7

Check it on the simulator

Keep the test key set. Create one account for each row below, with the email as the address of the user. The route calls verifyNewAccount, then NoResponse, then act.Log the id of each answer. It starts with asm_. If the answer has an account, also log account.risk.score and account.risk.decision. A first answer that is still pending has no account. To use an address again for a different account, add a +tag, as in allow+2@test.noresponse.org.The last row is the late result: an answer that has more risk after the gate acted. The gate on this page acts on the first answer, so it grants. The final answer raises the account’s decision to review, and NoResponse sends account.risk_changed. Admission and late decisions shows how the SDK enforces it.With your own login, give the SDK one function for each action, as Your own login shows.
Every simulated answer carries a test_scenario reason. Use it to tell a simulated answer from a live one.
8

Go live

  1. Set NORESPONSE_API_KEY to the live key from your verified email (step 1).
  2. Create a new account with your own email address.
NoResponse now assesses the answer against real sources. Its score comes from what the sources find, and it carries no test_scenario reason. A second account with the same email fires the seen_before reason. For a clean first answer, use a new address.Every answer carries an X-Request-ID header. Quote it, or the assessment id, when you write to us about an answer.To examine an answer, open the console and find its asm_ id on Assessments. You can also press ⌘K and paste the id. The assessment shows its score and reasons, its account, and the websites that held each identifier.

Next steps

Turn an assessment into a decision

Tune the rules. Add rules on reasons and confidence.

Webhooks

Receive late answers.

Pass your auth session

Send the session facts that the quickstart does not send.

Report outcomes

Tell NoResponse the outcome of each account, so that later scores improve.