Trying to understand token leases and when/how to renew

I’ve got a long-running process where I’m trying to re-use the authentication token initially obtained but that token is eventually expiring. I’m trying to figure out whether I should be renewing the token or re-authenticating.

When I first authenticate, I get a JSON blob back like this:

    "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": {
        "client_token": "zzzzzzzzzzzzzzzzzzzzzzzzzz",
        "accessor": "aaaaaaaaaaaaaaaaaaaaaaaa",
        "policies": [
        "token_policies": [
        "metadata": {
            "account_id": "999999999999",
            "auth_type": "iam",
            "canonical_arn": "arn:aws:iam::999999999999:role/vault_sd_automation",
            "client_arn": "arn:aws:sts::999999999999:assumed-role/vault_sd_automation/vault_sd_automation",
            "client_user_id": "AAAAAAAAAAAAAAAAAAAAA",
            "inferred_aws_region": "",
            "inferred_entity_id": "",
            "inferred_entity_type": ""
        "lease_duration": 2764800,
        "renewable": true,
        "entity_id": "qqqqqqqq-qqqq-qqqq-qqqq-qqqqqqqqqqqq",
        "token_type": "service"

After about a month of the process running, the token expires and any subsequent attempts to retrieve secrets from Vault fail with permission denied.

The JSON blob seems to suggest that the auth token is renewable. However, if I try to renew the token with /auth/token/renew-self, the returned JSON blob contains the following warning:

TTL of "768h0m0s" exceeded the effective max_ttl of "767h42m22s"; TTL value is capped accordingly

and the lease duration has not been reset to the originally-obtained TTL of 2764800. Repeated attempts to use that call continue to return a lower lease duration, showing that the token’s lifetime continues to run out.

If I use vault token lookup then that does show a “last_renewal” date/time string so Vault does think I’m renewing the token but the clock still ticks down.

What am I misunderstanding? Will the token only get “properly” renewed when the TTL has expired? Or can I not extend the lifespan of the token this way and I should, instead, be re-authenticating?

Hi Philip,

If I understand your question correctly, it sounds like you can renew the lease, but you’re seeing different ttl’s and you’re wondering why.

It’s actually an interesting aspect of the leasing system. Let’s suppose that you had a TTL of 8 hours, and a max TTL of 20 hours. Let’s also say you renew your token every 7 hours. If so, the first token you received would have a TTL of 8 hours. The second token you received would also have a TTL of 8 hours. The third token you received would have a TTL of 6 hours.

Why? Because 7 + 7 + 6 = 20. Each new TTL looks at how much time has been used from the current max, and returns the longest TTL it can. That longest TTL will either be the amount remaining of the max, of the cap for one TTL.

Does that make sense?

Thanks, @tyrannosaurus-becks.

So, if I’m understanding this correctly, if a token is leased with a TTL that matches the max TTL, that token cannot be renewed to extend the TTL further?

If I authenticate to get a Vault authentication token, therefore, and that token’s TTL matches the max TTL then once the lease expires, I have to re-authenticate. I cannot renew the lease on that authentication token?

If that is the case, is the best way to check when a token expires to query /sys/leases/lookup with the lease ID for the authentication token so that I then get back the expire_time value? Then, if my code is trying to use the token after that value, to re-authenticate.

Yes, that’s correct.

Yes, absolutely, that’s correct as well.

Yes, that would be one option.

Another option is, usually when you grab a secret or token from Vault, there’s some indication of how long it will last. For instance, when creating a token, the response includes a lease_duration and renewable field that can potentially be used to answer questions like, “Can I use this token right now?” and, “Can I renew this token?”

If you’d prefer not to deal with token renewal logic, another option would be to use the Vault agent, which takes care of obtaining and renewing tokens for you. Once you configure one of its authentication methods, it puts a token in a file for your application to use and it automatically renews the token or re-auths as needed, minimizing calls to Vault through caching. Then all your application needs to do is just always grab the present token from the file right before each call.