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

# Authentication

> Learn about the authentication methods for the Merchant API.

The preferred authentication method is to use HTTP Basic Auth with the API key username and password when making calls to the `call` method.

<Note>
  See [Find Your URL](/home/find-your-url) for information on finding the correct URL to use for your ShipStream instance.
</Note>

# HTTP Basic Auth

```bash title="HTTP Basic Auth Example" theme={null}
curl -X POST https://apiuser:password@example.shipstream.app/api/jsonrpc \
  -d '{"jsonrpc":2.0,"id":1234,"method":"call","params":[null,"warehouse.list",[]]}'
```

In this case, the `session_id` parameter to the `call` method (the first element of the `params` array) should be `null`.

# Session Login

`login(username, api_key)`

Another method is to use the `login` JSON-RPC method to obtain a session ID and use this session ID for subsequent requests to the `call` method.

The session ID can then be used as the first array element of the `params` parameter for subsequent requests to `call`.

<Warning>
  The session ID will expire after 24 hours at which time you will need to use `login` again. Do not call `login` before each request, instead consider
  using the HTTP Basic Auth method described above.
</Warning>

## `login()` Parameters

<ParamField path="username" type="string" required>
  The API user's username.
</ParamField>

<ParamField path="api_key" type="string" required>
  The API user's API key (password).
</ParamField>

## Return Value

Upon a successful login, the result will be a session ID which is a 32-character hexadecimal string.

## Login Example

```json Request theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "login",
    "params" : [
        "username",
        "password"
    ]
}
```

```json Response theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : "be1c13ed4e03f0ed7f1e4053dfff9658"
}
```

An example response for if the session is expired:

```json Session Expired theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : {
        "code" : -32005,
        "message" : "Session expired. Try to relogin."
    }
}
```

## Error Codes

| code | message                        |
| ---- | ------------------------------ |
| 2    | Access denied.                 |
| 6    | Required parameter is missing. |