Skip to main content

​
Overview

The Aries API uses OAuth2 with Bearer tokens (JWT format) for authentication. All API requests require a valid access token in the Authorization header.

​
Authentication Flow

​
1. OAuth2 Client Credentials

First, obtain your OAuth2 credentials from the Aries platform:
  • Client ID: Your application identifier
  • Client Secret: Your application secret key

​
2. Initialize the SDK

from aries_exchange import AriesClient

client = AriesClient(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# The SDK handles token management automatically

​
OAuth2 Authorization Flow

​
Authorization Code Flow

For applications that need user authorization: 
# Step 1: Initiate authorization
auth_url = client.oauth2.get_authorization_url(
    redirect_uri="https://yourapp.com/callback",
    scope=["read", "trade"],
    state="random_state_string"
)
print(f"Redirect user to: {auth_url}")

# Step 2: Handle the callback with authorization code
authorization_code = "code_from_callback"

# Step 3: Exchange code for tokens
tokens = client.oauth2.exchange_code(
    code=authorization_code,
    redirect_uri="https://yourapp.com/callback"
)

print(f"Access Token: {tokens.access_token}")
print(f"Refresh Token: {tokens.refresh_token}")
print(f"Expires In: {tokens.expires_in} seconds")

​
PKCE Support

For enhanced security in public clients (mobile apps, SPAs): 
import secrets
import hashlib
import base64

# Generate code verifier
code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).decode('utf-8').rstrip('=')

# Generate code challenge
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode('utf-8')).digest()
).decode('utf-8').rstrip('=')

# Step 1: Authorization with PKCE
auth_url = client.oauth2.get_authorization_url(
    redirect_uri="https://yourapp.com/callback",
    code_challenge=code_challenge,
    code_challenge_method="S256"
)

# Step 2: Exchange code with verifier
tokens = client.oauth2.exchange_code(
    code=authorization_code,
    redirect_uri="https://yourapp.com/callback",
    code_verifier=code_verifier
)

​
MFA Verification

If MFA is enabled: 
# After initial authorization, verify MFA
mfa_result = client.oauth2.verify_mfa(
    code="123456",  # 6-digit MFA code
    session_token=auth_response.session_token
)

# Then exchange for tokens
tokens = client.oauth2.exchange_code(
    code=mfa_result.authorization_code,
    redirect_uri="https://yourapp.com/callback"
)

​
Token Management

​
Refreshing Access Tokens

Access tokens expire after a set period. Use refresh tokens to obtain new access tokens: 
# Refresh the access token
new_tokens = client.oauth2.refresh_token(
    refresh_token=tokens.refresh_token
)

print(f"New Access Token: {new_tokens.access_token}")
print(f"Expires In: {new_tokens.expires_in} seconds")

​
Automatic Token Refresh

The SDK automatically refreshes tokens when they expire: 
# Configure automatic refresh
client = AriesClient(
    client_id="your_client_id",
    client_secret="your_client_secret",
    refresh_token="your_refresh_token",
    auto_refresh=True  # Enable automatic token refresh
)

# Make API calls without worrying about token expiration
accounts = client.users.get_user_accounts()

​
Using Bearer Tokens Directly

If you already have an access token: 
from aries_exchange import AriesClient

client = AriesClient(
    bearer_token="your_access_token"
)

# Make authenticated requests
user = client.users.get_current_user()

​
Security Best Practices

​
1. Store Credentials Securely

Never hardcode credentials in your source code: 
import os

client = AriesClient(
    client_id=os.getenv("ARIES_CLIENT_ID"),
    client_secret=os.getenv("ARIES_CLIENT_SECRET")
)

​
2. Use Environment Variables

Create a .env file (add to .gitignore): 
ARIES_CLIENT_ID=your_client_id
ARIES_CLIENT_SECRET=your_client_secret
ARIES_REFRESH_TOKEN=your_refresh_token
Load in your application: 
from dotenv import load_dotenv
import os

load_dotenv()

client = AriesClient(
    client_id=os.getenv("ARIES_CLIENT_ID"),
    client_secret=os.getenv("ARIES_CLIENT_SECRET")
)

​
3. Handle Token Expiration

from aries_exchange import AriesAPIError

try:
    user = client.users.get_current_user()
except AriesAPIError as e:
    if e.status_code == 401:
        # Token expired, refresh it
        tokens = client.oauth2.refresh_token(refresh_token)
        client.bearer_token = tokens.access_token
        # Retry the request
        user = client.users.get_current_user()

​
4. Scope Limitations

Request only the scopes you need: 
# Minimal scopes for read-only access
auth_url = client.oauth2.get_authorization_url(
    redirect_uri="https://yourapp.com/callback",
    scope=["read"]  # Only read access
)

# Full trading access
auth_url = client.oauth2.get_authorization_url(
    redirect_uri="https://yourapp.com/callback",
    scope=["read", "trade", "withdraw"]  # All permissions
)

​
OAuth2 Scopes

Available scopes:
  • read - Read account data, positions, and orders
  • trade - Place and cancel orders
  • withdraw - Withdraw funds from account
  • admin - Administrative operations

​
Error Handling

from aries_exchange import AriesAPIError

try:
    client = AriesClient(
        client_id="invalid_client_id",
        client_secret="invalid_secret"
    )
    user = client.users.get_current_user()
except AriesAPIError as e:
    if e.status_code == 401:
        print("Authentication failed: Invalid credentials")
    elif e.status_code == 403:
        print("Forbidden: Insufficient permissions")
    else:
        print(f"Error: {e.message}")

​
Rate Limiting

The Aries API enforces rate limits. If you exceed the limit: 
try:
    # Make API request
    result = client.orders.place_order(...)
except AriesAPIError as e:
    if e.status_code == 429:
        retry_after = e.headers.get('Retry-After')
        print(f"Rate limit exceeded. Retry after {retry_after} seconds")
        # Implement exponential backoff

​
Complete Example

import os
from aries_exchange import AriesClient, AriesAPIError

def main():
    # Initialize client
    client = AriesClient(
        client_id=os.getenv("ARIES_CLIENT_ID"),
        client_secret=os.getenv("ARIES_CLIENT_SECRET"),
        auto_refresh=True
    )

    try:
        # Get current user
        user = client.users.get_current_user()
        print(f"Authenticated as: {user.email}")

        # Get user accounts
        accounts = client.users.get_user_accounts()
        print(f"Found {len(accounts)} accounts")

    except AriesAPIError as e:
        if e.status_code == 401:
            print("Authentication failed")
        elif e.status_code == 403:
            print("Access forbidden")
        else:
            print(f"API Error: {e.message}")

if __name__ == "__main__":
    main()

​
Next Steps