Register error code 40167 for untrusted client type declarations

errors/codes/40167.md

@@ -0,0 +1,26 @@
+---
+code: 40167
+identifier: untrusted_client_type_declaration
+title: Client type declaration not signed by token
+summary: A connection or request declared itself as a server, but the token it authenticated with carries no matching client type claim. Only the key holder can make that declaration, so it must be signed into the token.
+---
+
+## What you should do
+
+If the traffic is from a server, add the `x-ably-clientType` claim, set to `server`, to the token issued for the client. The claim is signed by the API key that issues the token, which is what makes it trustworthy.
+
+You must be using JWT auth. See [our JWT auth documentation](https://ably.com/docs/auth/token/jwt) for how to add claims.
+
+If the traffic is not from a server, if you're using a Server SDK, switch to the equivalent Device SDK. If you're not using a Server SDK but you're setting an explicit `clientType=server` transportParam, just remove it, or switch to `clientType=device`.
+
+(A client authenticating directly with an API key can declare its client type as a connection or request parameter, because it already holds the key. So this all only applies if your servers need to use Token authentication).
+
+## Why it happens
+
+Client type determines whether traffic counts toward the account's monthly active users and whether it is subject to per-client-ID limits, so a client must not be able to exempt itself. Under Token authentication the signed claim is the only declaration Ably trusts: a connection parameter or agent identifier can be set by anyone holding the token, including an end user's device.
+
+The most common cause is the use of a Server SDK, with token authentication rather than API key auth, whose tokens were issued without the claim.
+
+## What you'll see
+
+The error is reported with code 40167 and HTTP status 401.

protocol/errors.json

@@ -367,6 +367,11 @@
       "title": "Unidentified client cannot modify own messages",
       "summary": "A message update or delete was rejected because the client is unidentified (it has no clientId) but holds only the \"own\" form of the relevant capability, message-update-own or message-delete-own, which can never apply to a client that has no messages of its own."
     },
+    "40167": {
+      "identifier": "untrusted_client_type_declaration",
+      "title": "Client type declaration not signed by token",
+      "summary": "A connection or request declared itself as a server, but the token it authenticated with carries no matching client type claim. Only the key holder can make that declaration, so it must be signed into the token."
+    },
     "40170": {
       "identifier": "error_from_client_token_callback",
       "title": "Token callback failed",