## Create an Account

Before you can use the API, you'll need to create a free account:

<Steps>
  <Step title="Sign up">
    Visit [dashboard.example.com/signup](https://dashboard.example.com/signup) 
    and create an account using your email address.
  </Step>
  
  <Step title="Verify your email">
    Check your inbox for a verification email and click the confirmation link.
  </Step>
  
  <Step title="Complete your profile">
    Add your company information and intended use case. This helps us 
    provide better support.
  </Step>
</Steps>

<Info>
New accounts start in sandbox mode with test credentials. You'll need to 
complete verification before accessing production API keys.
</Info>

## Get Your API Keys

<Steps>
  <Step title="Access the dashboard">
    Log in to your [dashboard](https://dashboard.example.com) and navigate 
    to **Settings > API Keys**.
  </Step>
  
  <Step title="Create an API key">
    Click **Create New Key** and choose the key type:
    
    - **Test keys** (`sk_test_...`) - Use in development and testing
    - **Production keys** (`sk_live_...`) - Use for real transactions
    
    <Warning>
    Production keys require account verification and may take 24-48 hours to activate.
    </Warning>
  </Step>
  
  <Step title="Copy and store securely">
    Copy your API key immediately - you won't be able to view it again.
    
    <Card title="Security Best Practices" icon="shield">
      - Never commit keys to version control
      - Store keys in environment variables
      - Rotate keys regularly
      - Use different keys for each environment
    </Card>
  </Step>
</Steps>

## Authentication

All API requests must be authenticated using your API key.

### Using API Keys

Include your API key in the `Authorization` header as a Bearer token:

```bash
curl https://api.example.com/v1/payments \
  -H "Authorization: Bearer sk_test_abc123"
```

<CodeGroup>
```javascript Node.js
const client = new APIClient({
  apiKey: process.env.API_KEY // Load from environment
});
```

```python Python
import os
client = APIClient(
  api_key=os.environ.get('API_KEY')
)
```
</CodeGroup>

### Authentication Errors

| Status | Error | Cause |
|--------|-------|-------|
| 401 | `invalid_api_key` | API key is missing or incorrect |
| 401 | `expired_api_key` | API key has been revoked |
| 403 | `insufficient_permissions` | Key doesn't have required scope |

## Install the SDK

We provide official SDKs for popular programming languages:

<Tabs>
  <Tab title="Node.js">
    **Requirements**: Node.js 16+ 
    
    ```bash
    npm install @example/api-client
    # or
    yarn add @example/api-client
    ```
    
    ```javascript
    const { APIClient } = require('@example/api-client');
    const client = new APIClient({ apiKey: 'your_api_key' });
    ```
  </Tab>
  
  <Tab title="Python">
    **Requirements**: Python 3.7+
    
    ```bash
    pip install example-api
    ```
    
    ```python
    from example_api import APIClient
    client = APIClient(api_key='your_api_key')
    ```
  </Tab>
  
  <Tab title="Ruby">
    **Requirements**: Ruby 2.7+
    
    ```bash
    gem install example-api
    ```
    
    ```ruby
    require 'example_api'
    client = ExampleAPI::Client.new(api_key: 'your_api_key')
    ```
  </Tab>
  
  <Tab title="REST API">
    Don't use an SDK? Make HTTP requests directly:
    
    ```bash
    curl https://api.example.com/v1/payments \
      -X POST \
      -H "Authorization: Bearer your_api_key" \
      -H "Content-Type: application/json" \
      -d '{"amount": 2000, "currency": "usd"}'
    ```
  </Tab>
</Tabs>

<Tip>
View all SDKs and code examples at [github.com/example/sdks](https://github.com/example/sdks)
</Tip>

## Environments

Our API supports two environments:

### Sandbox (Test Mode)

<Card title="Sandbox Environment" icon="flask">
  - Base URL: `https://api-sandbox.example.com`
  - API keys start with `sk_test_`
  - No real transactions are processed
  - Use test data (see [test cards](/docs/testing))
  - Rate limit: 100 requests/second
</Card>

Perfect for development, testing, and integration.

### Production (Live Mode)

<Card title="Production Environment" icon="rocket">
  - Base URL: `https://api.example.com`
  - API keys start with `sk_live_`
  - Real transactions are processed
  - Requires verified account
  - Rate limit: 1000 requests/second
</Card>

Use for real customer transactions.

### Switching Environments

Simply change the API key—our SDKs automatically detect the environment:

```javascript
// Test mode
const testClient = new APIClient({ 
  apiKey: 'sk_test_abc123' 
});

// Production mode
const liveClient = new APIClient({ 
  apiKey: 'sk_live_xyz789' 
});
```

<Warning>
Never use test API keys in production or production keys in development.
</Warning>

## Set Up Webhooks

Webhooks notify your application when events happen in your account.

<Steps>
  <Step title="Create an endpoint">
    Create a URL in your application that can receive POST requests:
    
    ```javascript
    app.post('/webhooks/payments', (req, res) => {
      const event = req.body;
      
      switch(event.type) {
        case 'payment.succeeded':
          // Handle successful payment
          break;
        case 'payment.failed':
          // Handle failed payment
          break;
      }
      
      res.sendStatus(200);
    });
    ```
  </Step>
  
  <Step title="Register the endpoint">
    In your dashboard, go to **Settings > Webhooks** and add your endpoint URL:
    
    - Development: `https://your-dev-server.com/webhooks/payments`
    - Production: `https://your-app.com/webhooks/payments`
  </Step>
  
  <Step title="Verify signatures">
    Always verify webhook signatures to ensure requests are from us:
    
    ```javascript
    const signature = req.headers['x-webhook-signature'];
    const isValid = client.webhooks.verify(req.body, signature);
    
    if (!isValid) {
      return res.sendStatus(401);
    }
    ```
  </Step>
</Steps>

<Tip>
Use [webhook.site](https://webhook.site) to test webhook delivery during development.
</Tip>

## Test Your Connection

Verify your setup with a simple API call:

```bash
curl https://api.example.com/v1/account \
  -H "Authorization: Bearer your_api_key"
```

Successful response:

```json
{
  "id": "acct_abc123",
  "email": "[email protected]",
  "status": "active",
  "environment": "test"
}
```

<Check>
If you received your account information, you're ready to start building!
</Check>