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

# Connect API

> OAuth-style API for accessing user data with consent

## Overview

The Connect API enables third-party marketplaces to access LootRush user data through an OAuth-style consent flow. Users explicitly grant permission for your application to access their profile, email, wallet, and KYC information.

***

## Prerequisites

Before implementing the Connect API, you must register your integration with LootRush:

1. **Contact LootRush** at [support@lootrush.com](mailto:support@lootrush.com) to request integration access
2. **Provide your redirect URI(s)** - The URL(s) where users will be redirected after granting consent
3. **Specify required scopes** - The data access permissions your integration needs

Once approved, LootRush will provide you with:

* **Integration ID** - Your unique integration identifier
* **API Key** - For authenticating API requests

<Warning>
  All redirect URIs and scopes are preconfigured by LootRush during the registration process and cannot be modified via the API.
</Warning>

***

## Integration Flow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Marketplace
    participant LootRush
    Marketplace->>LootRush: Redirect to /connect with integration_id
    LootRush->>User: Show consent screen
    User->>LootRush: Grant consent
    LootRush->>Marketplace: Redirect with consent_id
    Marketplace->>LootRush: GET /api/v1/consent/:consentId/user
    LootRush->>Marketplace: Return user data
```

### Step 1: Redirect User to Consent Page

Redirect the user to the LootRush Connect page:

```
https://www.lootrush.com/connect?integration_id=<your-integration-id>
```

| Parameter        | Required | Description                                               |
| ---------------- | -------- | --------------------------------------------------------- |
| `integration_id` | Yes      | Your unique integration identifier (provided by LootRush) |

### Step 2: User Grants Consent

The user reviews the requested permissions and clicks "Allow" to grant access. Only business admins can grant consent on behalf of their organization.

### Step 3: Receive Consent ID

After consent, the user is redirected to your preconfigured redirect URI with the consent ID:

```
https://your-app.com/callback?consent_id=<uuid>
```

If the user denies consent:

```
https://your-app.com/callback?error=access_denied
```

### Step 4: Fetch User Data

Use the consent ID to retrieve the user's data via the API.

***

## Authentication

All API requests must include your API key in the `x-api-key` header:

```bash theme={null}
x-api-key: your-api-key-here
```

<Warning>
  Requests with invalid or missing API keys will return a `401 Unauthorized` response.
</Warning>

***

## Scopes

The following scopes can be configured for your integration:

| Scope     | Description                                                |
| --------- | ---------------------------------------------------------- |
| `profile` | User's name and profile information                        |
| `email`   | User's email address and verification status               |
| `wallet`  | Connected wallet addresses (Base and Polygon)              |
| `kyc`     | Identity verification information (name, document, tax ID) |

<Info>
  Scopes are configured by LootRush during integration registration. Contact [support@lootrush.com](mailto:support@lootrush.com) to modify your integration's allowed scopes.
</Info>

***

## Get User Data

Retrieves the user data for a given consent.

<Endpoint>
  <Method>GET</Method>
  <Path>/api/v1/consent/:consentId/user</Path>
</Endpoint>

### Path Parameters

| Parameter   | Type   | Required | Description                                      |
| ----------- | ------ | -------- | ------------------------------------------------ |
| `consentId` | string | Yes      | The consent ID received after user authorization |

### Example Request

```bash theme={null}
curl -X GET "https://third-party.lootrush.com/api/v1/consent/550e8400-e29b-41d4-a716-446655440000/user" \
  -H "x-api-key: your-api-key-here"
```

### Response

<ResponseField name="consent_id" type="string">
  The consent identifier
</ResponseField>

<ResponseField name="integration_id" type="string">
  Your integration identifier
</ResponseField>

<ResponseField name="granted_at" type="string">
  ISO 8601 timestamp of when consent was granted
</ResponseField>

<ResponseField name="scopes" type="array">
  List of granted scopes
</ResponseField>

<ResponseField name="user" type="object">
  User data object containing the following fields based on granted scopes:

  <ResponseField name="profile" type="object">
    Profile information (requires `profile` scope):
    <ResponseField name="name" type="string">Full name</ResponseField>
    <ResponseField name="given_name" type="string">First name</ResponseField>
    <ResponseField name="family_name" type="string">Last name</ResponseField>
  </ResponseField>

  <ResponseField name="email" type="object">
    Email information (requires `email` scope):
    <ResponseField name="address" type="string">Email address</ResponseField>
    <ResponseField name="verified" type="boolean">Whether email is verified</ResponseField>
  </ResponseField>

  <ResponseField name="wallet" type="object">
    Wallet information (requires `wallet` scope):

    <ResponseField name="addresses" type="array">
      Array of wallet addresses, each with:
      <ResponseField name="chain" type="string">Blockchain network ("base" or "polygon")</ResponseField>
      <ResponseField name="address" type="string">Wallet address</ResponseField>
    </ResponseField>

    <ResponseField name="is_business" type="boolean">Whether this is a business account</ResponseField>
  </ResponseField>

  <ResponseField name="kyc" type="object">
    KYC information (requires `kyc` scope):
    <ResponseField name="email" type="string">Verified email from KYC</ResponseField>
    <ResponseField name="entity_type" type="string">Account type: "individual" or "business"</ResponseField>
    <ResponseField name="first_name" type="string">Legal first name</ResponseField>
    <ResponseField name="last_name" type="string">Legal last name</ResponseField>
    <ResponseField name="legal_name" type="string">Business legal name (null for individuals)</ResponseField>
    <ResponseField name="document_type" type="string">ID document type (e.g., "PASSPORT")</ResponseField>
    <ResponseField name="document_number" type="string">ID document number</ResponseField>
    <ResponseField name="tax_id" type="string">Tax identification number</ResponseField>
  </ResponseField>
</ResponseField>

### Example Response

```json theme={null}
{
  "consent_id": "550e8400-e29b-41d4-a716-446655440000",
  "integration_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "granted_at": "2024-01-15T10:30:00Z",
  "scopes": ["profile", "email", "wallet", "kyc"],
  "user": {
    "profile": {
      "name": "John Doe",
      "given_name": "John",
      "family_name": "Doe"
    },
    "email": {
      "address": "john.doe@example.com",
      "verified": true
    },
    "wallet": {
      "addresses": [
        {
          "chain": "base",
          "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2"
        },
        {
          "chain": "polygon",
          "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2"
        }
      ],
      "is_business": false
    },
    "kyc": {
      "email": "john.doe@example.com",
      "entity_type": "individual",
      "first_name": "John",
      "last_name": "Doe",
      "legal_name": null,
      "document_type": "PASSPORT",
      "document_number": "AB1234567",
      "tax_id": "123-45-6789"
    }
  }
}
```

***

## Error Responses

| Status Code | Error Message                                         | Description                                        |
| ----------- | ----------------------------------------------------- | -------------------------------------------------- |
| `401`       | `Unauthorized: Business ID not found`                 | Invalid or missing API key                         |
| `403`       | `Forbidden: Consent does not belong to your business` | The consent was granted to a different integration |
| `404`       | `Consent not found`                                   | The consent ID does not exist                      |
| `410`       | `Gone: Consent has been revoked`                      | The user has revoked this consent                  |

### Example Error Response

```json theme={null}
{
  "error": "Gone: Consent has been revoked",
  "revoked_at": "2024-01-20T15:00:00Z"
}
```

***

## Consent Revocation

Users can revoke consent at any time from their LootRush account settings. When a consent is revoked:

* API requests with that consent ID will return `410 Gone`
* Your application should handle this gracefully and prompt the user to reconnect

***

## Best Practices

1. **Store the consent ID securely**: Associate the consent ID with the user in your system for future API calls.

2. **Handle revocation**: Check for `410` responses and provide a way for users to reconnect.

3. **Request only necessary scopes**: When registering your integration, only request the scopes you actually need to build trust with users.

4. **Cache responsibly**: User data can change. Consider refreshing data periodically rather than caching indefinitely.

***

## Support

For API support, please contact:

* Email: [support@lootrush.com](mailto:support@lootrush.com)
* Dashboard: [LootRush Dashboard](https://www.lootrush.com/tokens/s/dashboard)