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

# OAuth Login

> Initiate OAuth 2.0 authorization flow for user authentication

<Note>
  This endpoint returns an HTML login page and must be opened in a browser. It cannot be tested via API calls.
</Note>

## Endpoint

```
GET https://oauth.sandbox.dcash.africa/login
```

## Query Parameters

<ParamField query="app_id" type="string" required>
  Your application's unique identifier provided during registration
</ParamField>

<ParamField query="redirect_url" type="string" required>
  The URL where users will be redirected after authentication
</ParamField>

## Try It Out

To test the OAuth flow, construct your URL and open it in a browser:

```bash theme={null}
https://oauth.sandbox.dcash.africa/login?app_id=YOUR_APP_ID&redirect_url=YOUR_REDIRECT_URL
```

<Card title="Open OAuth Login (Test)" icon="arrow-up-right-from-square" href="https://oauth.sandbox.dcash.africa/login?app_id=0000&redirect_url=https://example.com/callback">
  Opens with test values - modify the URL in your browser's address bar with your actual credentials
</Card>

## How It Works

This endpoint initiates the OAuth 2.0 authorization flow:

<Steps>
  <Step title="Redirect User">
    Your application redirects the user to this DCash URL
  </Step>

  <Step title="User Authenticates">
    User authenticates with their DCash credentials and approves access permissions
  </Step>

  <Step title="Token Sent to Webhook">
    Upon successful authentication, DCash sends an authorization token to your pre-registered webhook endpoint
  </Step>

  <Step title="User Redirected">
    The user is redirected to your specified `redirect_url`
  </Step>
</Steps>

## Authorization Token

<Info>
  The token will be sent to the webhook URL configured in your merchant account settings, not as a response from this endpoint.
</Info>

**Important Notes:**

* Store this token securely - it's required for making API calls on behalf of the user
* Tokens may be revoked by users through the DCash app or website
* If a token becomes invalid, you'll need to repeat the authorization flow

## Security Recommendations

<Warning>
  Follow these security best practices when implementing OAuth:
</Warning>

* Always validate that redirect URLs match your expected domain
* Use HTTPS for all redirect URLs
* Store tokens securely using appropriate encryption

## Webhook Payload

When authentication is successful, your webhook will receive this payload:

<ResponseField name="event" type="string">
  Type of event triggered (e.g., "user\_authorized")
</ResponseField>

<ResponseField name="user_email" type="string">
  Email address of the authenticated user
</ResponseField>

<ResponseField name="token" type="string">
  DCash token for subsequent API requests
</ResponseField>

```json Example Webhook Payload theme={null}
{
  "event": "user_authorized",
  "user_email": "test.user@dcash.africa",
  "token": "dcash_token_example"
}
```

## Example Implementation

Here's how to redirect a user to initiate the OAuth flow:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const appId = 'YOUR_APP_ID';
  const redirectUrl = 'https://yourapp.com/callback';

  // Redirect user to DCash OAuth endpoint
  window.location.href = `https://oauth.sandbox.dcash.africa/login?app_id=${appId}&redirect_url=${encodeURIComponent(redirectUrl)}`;
  ```

  ```python Python theme={null}
  import urllib.parse

  app_id = 'YOUR_APP_ID'
  redirect_url = 'https://yourapp.com/callback'

  # Construct OAuth URL
  oauth_url = f"https://oauth.sandbox.dcash.africa/login?app_id={app_id}&redirect_url={urllib.parse.quote(redirect_url)}"

  # Redirect user (implementation depends on your framework)
  ```

  ```php PHP theme={null}
  <?php
  $appId = 'YOUR_APP_ID';
  $redirectUrl = 'https://yourapp.com/callback';

  // Construct OAuth URL
  $oauthUrl = "https://oauth.sandbox.dcash.africa/login?app_id=" .
              $appId .
              "&redirect_url=" .
              urlencode($redirectUrl);

  // Redirect user
  header("Location: " . $oauthUrl);
  exit();
  ?>
  ```
</CodeGroup>

<Check>
  After receiving the token via webhook, you can use it to make authenticated API requests on behalf of the user.
</Check>