Create & use an API key¶

Password-derived tokens are meant for interactive sessions. For scripts, pipelines, and services you should use API keys: they are long-lived, carry only the scopes you grant them, and can be revoked individually without touching your password or other keys.

1. Create a key¶

Any authenticated user can create API keys for their own account:

    client.api_keys.create(
        name='My API Key',
        scopes=['viewer', 'editor'],
    )

By default the key's token is saved to ineepy.toml, so the next bare Ineepy() picks it up. To receive the token instead of saving it, pass save_token=False:

    token = client.api_keys.create(
        name='My API Key',
        scopes=['viewer', 'editor'],
        save_token=False,
    )

with Ineepy(token=token) as api_key_client:

Set an expiry¶

expires_at accepts a datetime or an ISO-8601 string; without it, keys effectively never expire (server default 2099-12-31). scopes accepts a single scope name or an iterable of names:

    report_token = client.api_keys.create(
        name='quarterly-report-key',
        scopes='viewer',
        expires_at='2031-01-01T00:00:00',
        save_token=False,
    )

2. Use the key¶

An API-key token is a drop-in replacement for a password token — pass it to the client directly:

with Ineepy(token=token) as client:
    user, etag = client.users.get('me')
    print(f'Logged in as {user.username} ({user.email})')

Or let a saved ineepy.toml / the INEEPY_TOKEN environment variable supply it (see Authentication).

3. Inspect your keys¶

list() returns metadata for every key on your account — name, scopes, creation and expiry timestamps, and the jti identifier used for revocation (never the token itself):

    api_keys = api_key_client.api_keys.list().items
    print(f'API Keys: {[k.name for k in api_keys]}')

4. Revoke a key¶

Revocation sets the key's expiry to now — the key stays in list() output, but any request using it fails with UnauthorizedError immediately:

    key = client.api_keys.list(
        filters='name:eq:quarterly-report-key',
        order_by='created_at:desc',
    ).items[0]
    client.api_keys.revoke(key.jti)

    try:
        with Ineepy(token=report_token) as revoked_client:
            revoked_client.api_keys.list()
    except UnauthorizedError:
        print('Revoked key is rejected')

Best practices¶

• Never commit tokens to version control — use environment variables or secret managers
• Set expiration dates — rotate keys regularly
• Use separate keys per application — easier to revoke if compromised
• Revoke unused keys — reduce your attack surface

See also¶

• API Keys resource reference
• api_keys API reference