# Token Authentication (/sdks/ruby/how-to/connection/token-auth)



## Overview [#overview]

**Token authentication** proves a client's identity to a KubeMQ server that has authentication enabled, without embedding a username/password or issuing per-client TLS certs. It's the mechanism you reach for in shared clusters, multi-tenant deployments, or any environment where you need to control and audit which clients are allowed to connect — the token is issued and revoked by your identity provider, not baked into the application.

The token travels as a bearer value in gRPC metadata attached to every outgoing request, set via the `auth_token:` keyword argument when constructing `KubeMQ::PubSubClient`. The server validates it before honoring any call, including the initial handshake. Because a static token eventually expires, source it from an environment variable or a secrets manager rather than a literal, so rotation only requires updating the environment and reconnecting.

**Gotchas:** an invalid or expired token isn't rejected until the first real call — call `ping` right after connecting so failures surface as a `KubeMQ::AuthenticationError` immediately instead of on your first business request; never hardcode a real token in source; and the client's `auth_token` is static for its lifetime, so long-running processes holding short-lived JWTs need to reconnect on a schedule rather than expecting in-place refresh.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000` with authentication enabled
* Ruby SDK installed (`gem install kubemq`)

## Code [#code]

```ruby title="main.rb"
require 'kubemq'

address = ENV.fetch('KUBEMQ_ADDRESS', 'localhost:50000')
token = ENV.fetch('KUBEMQ_AUTH_TOKEN', 'your-auth-token-here')

begin
  client = KubeMQ::PubSubClient.new(
    address: address,
    client_id: 'auth-token-example',
    auth_token: token
  )
  puts "Connected with auth token to #{address}"

  info = client.ping
  puts "Ping OK: host=#{info.host}, version=#{info.version}"
rescue KubeMQ::Error => e
  puts "KubeMQ error: #{e.message}"
ensure
  client&.close
  puts 'Connection closed'
end
```

## How It Works [#how-it-works]

* The `auth_token` is sent as a bearer token in the gRPC metadata for every request.
* Store tokens in environment variables or a secrets manager — never hard-code credentials.
* If authentication fails, the SDK raises `KubeMQ::AuthenticationError`.
* Review timeouts, channel names, and client IDs before running against shared environments.

## Related [#related]

* [Ruby SDK Reference](/sdks/ruby/reference)
* [Connect](/sdks/ruby/tutorials/connect)
* [TLS Setup](/sdks/ruby/how-to/tls/tls-setup)