Quickstart

This guide will walk you through the essential steps to integrate your AI tool with Memoram.

Integration Process Overview

1. Register your Application: Create a developer account and register your application in the Memoram Developer Portal.
2. Get API Key: Obtain your developer API key from the Developer Portal.
3. Get JWT Token: Exchange your API key for a short-lived JWT Bearer Token using the /auth/token endpoint. This token is required for most subsequent API calls.
4. Implement User Authorization (OAuth 2.0): Redirect users to Memoram to grant your application permission to access their memory.
5. Exchange Authorization Code: Exchange the received authorization code for user-specific tokens and the crucial memory_key using the /oauth/token endpoint.
6. Request Access Credentials: Use the memory_key and your JWT to request access via the /access-requests endpoint. The user approves this in their Memoram dashboard.
7. Get Encryption Key: Once approved, retrieve the user’s encryption_key from /access-requests/{request_id}/credentials.
8. Access Memory Blobs: Use your JWT, the user’s ID, and the encryption_key to retrieve, create, update, or delete memory blobs using the /memory-blobs endpoints.
9. Manage Tags: Retrieve available tags using the /tags endpoints.

Authentication and Authorization

Memoram uses two primary methods for securing API access:

1. Developer JWT Token: For authenticating your application itself.
2. User OAuth 2.0 Flow: For authorizing your application to access a specific user’s memory.

1. Getting Your Developer JWT Token

Before making most API calls, you need a short-lived JWT Bearer token. Exchange your permanent developer API key (found in the Developer Portal) for this token.

curl -X POST https://api.memoram.app/api/v1/auth/token \\
  -H "Content-Type: application/json" \\
  -d '{
    "api_key": "YOUR_DEVELOPER_API_KEY"
    # Optional: "expires_in": 3600
  }'

The response will contain your JWT (token field). Include this token in the Authorization: Bearer <token> header for subsequent API calls.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-01T12:00:00Z",
  "token_type": "Bearer"
}

2. Authorizing User Memory Access (OAuth 2.0 - Conceptual Overview)

While the full OAuth 2.0 flow (redirecting users, handling callbacks) is standard, the key Memoram-specific steps involve:

a. Getting the User’s Memory Key: After a user successfully authenticates and authorizes your app via the standard OAuth redirect_uri callback, you will receive an authorization_code. Exchange this code for tokens.

# Simplified - Represents the POST request to exchange the code
POST https://auth.memoram.io/oauth/token # Note: This endpoint might differ from the API endpoint
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE_FROM_REDIRECT&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=YOUR_REDIRECT_URI

b. Receiving Tokens and Memory Key: The response to the code exchange includes the user’s memory_key.

{
  "access_token": "USER_ACCESS_TOKEN", // Standard OAuth token
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "USER_REFRESH_TOKEN",
  "memory_key": "USER_OBTAINED_MEMORY_KEY" // Crucial key needed for access requests
}

c. Requesting Access via API: Now, using your Developer JWT Token, you request formal access using the user’s memory_key.

curl -X POST https://api.memoram.app/api/v1/access-requests \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer YOUR_DEVELOPER_JWT_TOKEN" \\
  -d '{
    "memoryKey": "USER_OBTAINED_MEMORY_KEY",
    "reason": "[Your App Name] needs access to read and write memories to provide personalized assistance."
  }'

d. User Approval: The user sees this request in their Memoram dashboard and must approve it.

e. Getting Credentials: Once approved, use the request ID from step (c) to fetch the user’s ID and the necessary encryption_key.

curl -X GET https://api.memoram.app/api/v1/access-requests/{request_id}/credentials \\
  -H "Authorization: Bearer YOUR_DEVELOPER_JWT_TOKEN"

{
  "user_id": "user-uuid-from-memoram...",
  "memory_key": "USER_OBTAINED_MEMORY_KEY",
  "encryption_key": "hex-encoded-encryption-key...", 
  "key_version": 1
}

Now you have the user_id and encryption_key needed to interact with the /memory-blobs and /tags endpoints for that specific user.