Skip to main content
Update your request and response handling together. Changing the version in a URL is not enough.

​
Use the correct route family

The v1 base path is /api/v1. The v2 base path is /v2. Keep the v1 parser for calls that still use v1. Use the v2 lookup guide for the new lookup request.

​
Check your existing key first

Both API versions use a Dock API key in Authorization: Bearer YOUR_API_KEY. Keep the secret separate from your PID. Check an existing credential with GET /v2/key, then test a read-only lookup with the correct server context. A key appearing in the account list does not prove that a Bearer request succeeds. Secret reveal availability is also separate from authentication. A documentation or API-version change does not by itself require you to rotate a working key. If a request fails, check the key’s status, scope, restrictions, and HTTP response before replacing it. Never send the secret to support.

​
Update response parsing

Successful v2 JSON responses contain status, data, meta, and timestamp. Read the HTTP status before using data. Preserve IDs as strings. V1 responses differ between routes. Do not apply one v1 response parser to every lookup and session endpoint. V1 session fields such as sid and status_reason become id and statusReason in v2. The v2 session status completed replaces the older complete status.

​
Update verification sessions

Create v2 sessions with a JSON body containing pid and clientId. Supply guildId when the integration needs server context. Use the verifyUrl returned by Dock. Read a session with GET /v2/sessions/:id. The stream endpoint is GET /v2/sessions/:id/stream. V1 stream events include status, complete, and expired; v2 uses session events. Update the event listener and its JSON parser together. V1 link-write routes use query parameters; v2 link writes use JSON bodies. Test writes only in an environment authorized for changes.

​
Verify the result

  1. Confirm key authentication independently from the account key list.
  2. Compare a known linked account and a known missing link with the same server scope.
  3. Check invalid input, forbidden scope, and rate-limit responses.
  4. Test session creation, polling, terminal status, and streaming in an authorized test environment.
  5. Keep your previous integration configuration available until your own checks pass.
A read-only preview cannot validate link writes or complete a verification workflow that changes an account.