> ## Documentation Index
> Fetch the complete documentation index at: https://memoram.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://developers.memoram.app).
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.

```bash theme={null}
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.

```json theme={null}
{
  "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.

```bash theme={null}
# 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`.

```json theme={null}
{
  "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`.

```bash theme={null}
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`.

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

```json theme={null}
{
  "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.