Security Policies

Overview

Security policies let you restrict when and how OAuth tokens and managed secrets can be accessed. Policies are enforced in real-time on every credential retrieval — if any rule fails, access is denied.

Time-Based

Restrict access to business hours and/or weekdays only

IP Allowlist

Only allow access from specific IPs or CIDR ranges

Grant TTL

Set expiration dates on individual grants

Policies apply to both OAuth grants and managed secrets. The same rules protect all credential types.

App-Level Policies

App-level policies apply to all connections for a given provider within an app. Configure them in the Developer Portal under Policies.

Time-Based Access

Restrict credential access to specific time windows:

Rule	Description
Business hours only	9:00 AM – 5:00 PM in the configured timezone
Weekdays only	Monday through Friday
Timezone	Any IANA timezone (e.g., `America/New_York`, `Europe/London`). Defaults to UTC.

Rules combine with AND logic — if you enable both business hours and weekdays, access is only allowed during business hours on weekdays.

IP Allowlist

Restrict credential access to specific IP addresses or ranges:

IPv4 addresses (e.g., 203.0.113.50)
IPv6 addresses (e.g., 2001:db8::1)
CIDR ranges (e.g., 203.0.113.0/24, 10.0.0.0/8)

Use CIDR ranges for office networks or VPNs rather than listing individual IPs.

Configuring Policies

Open the app in the Developer Portal

Go to portal.alterauth.com and select the app

Go to Policies

Click Policies in the app sidebar. Only providers you’ve already configured (OAuth or managed secret) appear here.

Add or edit a policy

Click Add Policy (or edit an existing one) next to a provider:

Time restrictions: Enable business hours and/or weekdays, select timezone
IP allowlist: Add IPv4/IPv6 addresses or CIDR ranges

Save

Click Save Policy. Changes take effect immediately for new credential retrievals.

Policy Examples

Business hours + office IP only:

{
  "time_restrictions": {
    "business_hours_only": true,
    "weekdays_only": true,
    "timezone": "America/New_York"
  },
  "ip_allowlist": ["203.0.113.0/24"]
}

Weekdays only (any IP, any hour):

{
  "time_restrictions": {
    "weekdays_only": true,
    "timezone": "UTC"
  }
}

IP-restricted only (any time):

{
  "ip_allowlist": [
    "203.0.113.0/24",
    "10.0.0.0/8",
    "2001:db8::/32"
  ]
}

Grant-Level Policies (TTL)

Grant-level policies set an expiration date on individual grants, independent of app-level policies.

Setting TTL During OAuth Flow

Pass a grant_policy when creating a Connect session to set TTL on new grants:

session = await vault.create_connect_session(
    allowed_providers=["google", "slack"],
    grant_policy={
        "max_ttl_seconds": 2592000,      # 30-day upper bound
        "default_ttl_seconds": 604800,   # 7-day default shown in UI
    },
)

Parameter	Description
`max_ttl_seconds`	Maximum lifetime a grant can have. Users cannot extend beyond this.
`default_ttl_seconds`	Default duration shown in the Alter Connect UI. Users can adjust within bounds.

How TTL Works

When a grant expires (expires_at < now), any vault.request() call raises (Python) / throws (TypeScript) a GrantExpiredError
End users can view and extend TTL in the Wallet Dashboard, up to the developer-set max_ttl_seconds bound

Handling Policy Errors

When a policy denies access, the SDK raises a specific error depending on the cause. Handle all three policy-related errors:

from alter_sdk import HttpMethod
from alter_sdk.exceptions import (
    GrantExpiredError,
    PolicyViolationError,
    ReAuthRequiredError,
)

try:
    response = await vault.request(
        HttpMethod.GET,
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        grant_id=grant_id,
    )
except GrantExpiredError:
    # Grant TTL expired — prompt user to reconnect
    print("Connection expired. Please reconnect via Alter Connect.")
except PolicyViolationError as e:
    # Time-based or IP allowlist denial
    print(f"Access denied by policy: {e.message} (rule: {e.policy_error})")
except ReAuthRequiredError:
    # OAuth token invalid — prompt user to re-authorize
    print("Re-authorization required.")

Error	When It’s Raised	Action
`GrantExpiredError`	Grant TTL has expired	Prompt user to reconnect via Alter Connect
`PolicyViolationError`	Time-based restriction or IP allowlist denial	Check `policy_error` / `policyError` for the specific rule; adjust timing or IP
`ReAuthRequiredError`	Connection requires re-authorization (revoked by provider, deleted by user, or otherwise invalidated)	Redirect user to re-authorize via Alter Connect

Policy Evaluation Order

When a credential is requested, policies are evaluated in this order:

Grant TTL — is the grant expired?
Time restrictions — is it within business hours / a weekday?
IP allowlist — is the client IP in the allowed list?

All rules use AND logic — every configured rule must pass for access to be granted.

If no policy is configured for a provider, all credential accesses are allowed (permissive default). We recommend configuring at least time-based or IP restrictions for production applications.

Custom Policies

The built-in policy types cover common access control patterns. For requirements beyond time-based, IP allowlist, and TTL policies, Alter Vault supports custom policies:

URL Restrictions

Limit which API endpoints a credential can be used against

HTTP Method Restrictions

Allow read-only access (GET only) for certain actors

Rate Limiting

Cap how many requests a credential can serve per time window

Custom Rules

Any logic tied to end-user identity, actor identity, or request context

Custom policies are enforced at the same layer as built-in policies, with the same fail-closed guarantees, audit logging, and policy violation errors.

Set up custom policies

Contact the team to configure custom policies for a specific use case.

Fail-Closed Security

If the policy engine is temporarily unavailable, the system denies all credential access rather than bypassing policies. This ensures security is maintained even during outages.

Policy Violations in Audit Logs

Every policy denial is logged with the specific reason:

Which rule failed (time restriction, IP allowlist, TTL)
The policy decision (ALLOW or DENY)
Full request context (who, what, when)

View policy violations in the Developer Portal under Audit Logs — filter by event type to see denials.

Best Practices

Start permissive, tighten gradually

Enable audit logging first to understand access patterns. Then add policies based on actual usage — this avoids accidentally blocking legitimate access.

Use CIDR ranges over individual IPs

For office networks and VPNs, use CIDR notation (203.0.113.0/24) rather than listing individual IPs. This is easier to maintain and accommodates DHCP changes.

Set TTL for sensitive integrations

For connections that access sensitive data (financial APIs, healthcare systems), set a grant TTL to limit exposure if credentials are compromised.

Match timezone to the team

Set the policy timezone to match where the team operates. For distributed teams, consider using UTC and broader time windows.

Next Steps

Audit Logs

Monitor policy decisions and violations

Developer Portal

Configure policies in the portal

Architecture

Security model and encryption details

Python SDK

SDK error handling for policy violations

Getting Started

Guides

SDKs

Identity Providers

OAuth Providers

Managed Secret Providers

Reference

Overview

Time-Based

IP Allowlist

Grant TTL

App-Level Policies

Time-Based Access

IP Allowlist

Configuring Policies

Policy Examples

Grant-Level Policies (TTL)

Setting TTL During OAuth Flow

How TTL Works

Handling Policy Errors

Policy Evaluation Order

Custom Policies

URL Restrictions

HTTP Method Restrictions

Rate Limiting

Custom Rules

Set up custom policies

Fail-Closed Security

Policy Violations in Audit Logs

Best Practices

Next Steps

Audit Logs

Developer Portal

Architecture

Python SDK

Getting Started

Guides

SDKs

Identity Providers

OAuth Providers

Managed Secret Providers

Reference

Documentation Index

​Overview

Time-Based

IP Allowlist

Grant TTL

​App-Level Policies

​Time-Based Access

​IP Allowlist

​Configuring Policies

​Policy Examples

​Grant-Level Policies (TTL)

​Setting TTL During OAuth Flow

​How TTL Works

​Handling Policy Errors

​Policy Evaluation Order

​Custom Policies

URL Restrictions

HTTP Method Restrictions

Rate Limiting

Custom Rules

Set up custom policies

​Fail-Closed Security

​Policy Violations in Audit Logs

​Best Practices

​Next Steps

Audit Logs

Developer Portal

Architecture

Python SDK

Overview

App-Level Policies

Time-Based Access

IP Allowlist

Configuring Policies

Policy Examples

Grant-Level Policies (TTL)

Setting TTL During OAuth Flow

How TTL Works

Handling Policy Errors

Policy Evaluation Order

Custom Policies

Fail-Closed Security

Policy Violations in Audit Logs

Best Practices

Next Steps