Status code · Authentication
BadIdentityTokenInvalid
BadToken shape
BadIdentityTokenInvalid is about the shape of the token, not the credentials. The token type or its policy id does not match what the endpoint offers, or its encrypted password was formed with the wrong policy. Read the endpoint's UserIdentityTokens list and use one of the policy ids it publishes.
Defined behaviour: The user identity token supplied is not a form the endpoint accepts, or is not correctly formed for the policy it names. (our description of the condition this code reports)
What you actually see
ActivateSession fails immediately regardless of which username and password you try, and anonymous connection to the same endpoint may work fine.
Why it happens
- Token type the endpoint does not offerEach EndpointDescription lists the user identity token types it accepts. Sending a username token to an endpoint that only accepts anonymous and certificate tokens is refused on shape alone. This is why a client that works against one endpoint of a server fails against another endpoint of the same server.
- PolicyId not one the endpoint publishedEvery UserTokenPolicy in the endpoint has a PolicyId string, and the token you send must name one of them. Clients that hardcode a policy id, or leave it empty when the server requires one, are rejected. The strings are server-defined, so they must be read from GetEndpoints rather than assumed.
- Password encrypted with the wrong security policyA username token's password is encrypted using the security policy the UserTokenPolicy names, which may differ from the channel's own policy. Encrypting with the channel policy when the token policy specifies a different one produces a token the server cannot decrypt, and the result is an invalid token rather than a wrong password.
- Token sent over an endpoint with no encryptionWhere the token policy requires encryption and the channel provides none, there is no way to protect the password. Servers refuse the combination. This also means username and password over a MessageSecurityMode of None sends credentials in clear where a server permits it at all, which is its own problem.
- Malformed issued tokenFor IssuedToken types carrying a JWT or similar, a token that is expired, truncated, wrongly encoded or issued for a different audience is invalid in form. The distinction from a rejected credential can be subtle, and the server may not be able to tell you more without leaking information.
How to fix it
In diagnostic order: work down, do not skip ahead.
- Call GetEndpoints and read the token policiesFor the endpoint you intend to use, list its UserIdentityTokens entries with their TokenType, PolicyId, SecurityPolicyUri and IssuerEndpointUrl. That tells you exactly what is acceptable. Do this before writing credentials into a configuration file.
- Pick the endpoint that offers the token type you haveA server usually publishes several endpoints with different security modes and token policies. Select on both the security requirement and the token type rather than taking the first endpoint in the list, and never select on a best-available basis that could silently land on no security.
- Use the PolicyId string verbatimCopy the PolicyId from the endpoint description into the token. Do not normalise its case, do not translate it, and do not carry it between servers. It is an opaque server-defined identifier.
- Let the SDK build the tokenPassword encryption for a username token, including which policy to use and how to lay out the encrypted block, is fiddly and stack-specific. Use the SDK's user identity type rather than constructing the token yourself; hand-built tokens are the most common source of this code.
- Connect with a secured endpointChoose an endpoint with Sign or SignAndEncrypt so the token can be protected properly. Beyond fixing the error, this is the difference between sending a password protected and sending it in clear.
- For issued tokens, verify the token independentlyDecode the token and check its expiry, issuer and audience against what the server's IssuerEndpointUrl implies. An expired or misaddressed token fails on form, and checking it outside the OPC UA client removes a whole layer from the investigation.
Where it shows up, by tool and stack
| Tool / stack | What to do there |
|---|---|
| UA-.NETStandard (C#) | Pass a UserIdentity built from a UserNameIdentityToken, X509 certificate or issued token and the stack selects the policy from the endpoint. Its identity provider interfaces cover JWT and OAuth-style issued tokens for the more complex cases. |
| asyncua (Python) | Client.set_user and set_password build the token, and the client selects the policy from the endpoint description. Building the token manually is where this code appears; log the endpoint's token policies when it does. |
| node-opcua | The userIdentityInfo object carries the token type and credentials, and the library derives the policy from the endpoint. Confirm you connected to an endpoint whose token policies include the type you set. |
| open62541 (C) | The client takes a username and password directly for the common case; for other token types you build the ExtensionObject yourself, so the policy id and encryption must match the endpoint description exactly. |
| UaExpert | The connection dialog lists the endpoint's available authentication settings, so it is the fastest way to see which token types and policies a server actually publishes before coding against them. |
| Prosys | The client lets you select the token type per connection, which makes it useful for confirming which combinations a server accepts when its published endpoint list is ambiguous. |
What it looks like in the log
ActivateSession failed: BadIdentityTokenInvalid (tokenType UserName, policyId username_basic256sha256)
Endpoint publishes token policies: Anonymous, Certificate; username token refused
Password encryption policy mismatch for user token on endpoint opc.tcp://192.0.2.20:4840Confirm the fix
Confirm the session activates and that the server's session diagnostics show the identity you intended rather than anonymous, which is what a fallback in your client would produce.
Stop it happening again
Read token policies from GetEndpoints at connect and select the endpoint on both security mode and token type, keep policy ids out of static configuration, and always let the SDK construct and encrypt the token.
Related status codes
Concepts on this page
Stuck on more than one of these? The troubleshooting clinic works through broken configurations end to end, on camera.
Troubleshooting clinic →Last verified 7 September 2026 against OPC UA 1.05.07. OPC UA Connect is an educational resource and is not affiliated with the OPC Foundation.