Skip to main content
The server SDKs are the official Didit libraries for your backend. Each one calls the server endpoints of the API reference with typed requests and responses, verifies the webhooks Didit sends you, and checks the tokens of Didit Authentication. No 1.0.1 release has the two Google Wallet endpoints yet: start a Google Wallet verification and submit a wallet response. The Python, Node.js, Java, PHP, Ruby and .NET SDKs have every other server endpoint. Go 1.0.1 also lacks nine more, most of them Travel Rule endpoints: see Endpoints not in the Go SDK yet. Use them wherever your code holds a Didit API key: creating verification sessions, reading decisions, calling the standalone APIs, managing users, businesses, workflows and cases, screening transactions and wallets, and the Travel Rule. In the browser or a mobile app, use the web and native SDKs instead: they present the verification flow to your user and never hold your API key. Server endpoint pages of the API reference, including the Database Validation service pages, show a code sample for each server SDK next to the cURL request. A sample is shown once the SDK’s latest release has the endpoint and every field the sample sends: an endpoint or field added to the API gets its samples with the next release of each SDK. No 1.0.1 release has the 16 Database Validation request fields added after it was generated, such as vin or bank_account_number, so the service pages that send them show cURL only.

​
Install

​
Configure

Every SDK reads the same environment variables, so a client created with no options is ready to use. Edge runtimes have no process environment: there, pass the API key to the Node.js client as an option. Anything you can set through the environment you can also pass to the client, along with the base URL, timeout, retries, default headers and your own HTTP client. Create one client per process and share it: it keeps a connection pool and is safe to use from several threads or tasks. The account methods (programmatic registration: register, sign in, organizations and applications) call https://apx.didit.me/auth/v2 and never send your API key. Sign in with account.login, then pass the returned access token to the client as its account token.

​
What every SDK does

  • Resources and methods. Calls follow the API’s resources: client.<resource>.<method>(...), for example sessions.create, sessions.retrieve_decision or transactions.create, in each language’s own case. Path ids are positional arguments; the body and the query are one set of named fields. Python, Node.js, PHP and Ruby use the API’s own field names (workflow_id); Go, Java and .NET use their language’s case (WorkflowID, workflowId, WorkflowId).
  • Lists. List methods page through every result for you (limit and offset underneath), and also expose each page with count, next, previous and results. In Ruby, auto_paging_each goes through every page, and a page’s total_count, next_url and previous_url are the API’s count, next and previous.
  • Files. Uploads (document images, selfies, proof of address, imports) accept a path, bytes or a stream. Downloads (session PDFs, reports) return bytes or a stream, never parsed JSON.
  • Forward compatibility. A response field or an enum value the SDK version does not know yet is kept and readable, never an error, so an API addition does not break a deployed integration.
  • Webhooks. webhooks.verify checks the X-Signature-V2 and X-Signature headers and the timestamp of a delivery with your webhook secret, and returns a typed event. It accepts a list of secrets while you rotate one. See Webhooks for the signature scheme.
  • Authentication. An Authentication helper verifies the access and ID tokens your Authentication issuer signs, and calls its token, session and step-up endpoints. It never uses your API key.

​
Errors, retries and timeouts

Every error derives from DiditError. In Go, every error implements the didit.Error interface and is a pointer type such as *didit.NotFoundError. Java, PHP and .NET name them with their usual Exception suffix and write API as Api: DiditException, ApiStatusException, NotFoundException. The SDKs retry a failed request up to 2 times, with exponential backoff from 0.5 seconds (full jitter, at most 8 seconds) and honouring Retry-After. GET, HEAD, PUT and DELETE are retried on connection errors, timeouts, 408, 429 and 5xx. POST and PATCH are retried only on 429 or when the connection failed before the request was sent, so a retry never creates a second session or transaction. The default timeout is 60 seconds. Every response also exposes the raw HTTP status, headers and request id. See Rate limiting for the limits behind 429.

​
Versioning and support

  • The SDKs follow semantic versioning. When an endpoint leaves the API or its method is renamed, the old method stays for at least one more minor version, marked deprecated, so your code keeps building while you move to the new one.
  • They are generated from the published API contract (openapi-25.json and openapi-auth.json) and check it every day, so a new endpoint or field arrives in a regular release of all seven SDKs.
  • Each SDK supports the minimum runtime in the table and every newer release. Its tests run on the minimum and on each newer release, or each long-term support release for Node.js and Java.
  • Each repository’s CHANGELOG.md lists the changes of every release.
  • Report a security issue privately through the SDK repository’s security advisories or to support@didit.me.