> For the complete documentation index, see [llms.txt](https://docs.luganodes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.luganodes.com/apis/staking-apis-v2/authentication.md).

# Authentication

* [Sign up](#sign-up)
* [Create API Key](#create-api-key)
* [List API Keys](#list-api-keys)
* [Revoke API Key](#revoke-api-key)

## Sign up 

<mark style="color:green;">`POST`</mark> `/user/signup`

Create an account for your organization with Luganodes. Please contact <hello@luganodes.com> in order to approve your organisation and receive an API key once you've signed up using this endpoint.

#### Request Body

```json
{
  "email": "testuser@example.com",
  "password": "TestPass123",
  "org": "Test Organization",
  "scope": {
    "sui": {
      "validator_addresses": ["0x7e254f0f55e24b8a6995567241618f750d0d94f2cf49b36703869779d2ee4327"],
      "delegator_addresses": ["0xfaiojf923h2i.....", "0x329hipnasfnweufaw....."]
    }
  }
}
```

| Name                                       | Type   | Description                             |
| ------------------------------------------ | ------ | --------------------------------------- |
| email<mark style="color:red;">\*</mark>    | String | Organization email                      |
| password<mark style="color:red;">\*</mark> | String | Password for organization account       |
| org<mark style="color:red;">\*</mark>      | String | Organization Name                       |
| scope<mark style="color:red;">\*</mark>    | Object | Object containing whitelisted addresses |

> **Note**: If you are not sure what needs to be added as a scope, apply with an empty scope object and get in touch with our team at <hello@luganodes.com>

{% tabs %}
{% tab title="202: Accepted" %}

```javascript
{
    "message": "Registration request received and is pending approval."
}
```

{% endtab %}

{% tab title="409: Conflict" %}

```json
{
    "error": "A user with this email already exists",
    "code": "USER_EXISTS"
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
    error: "Invalid JSON payload",
    code: "INVALID_JSON"
}
```

```json
{
    "error": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
        {
            "field": "email",
            "message": "Please provide a valid email address"
        }
    ]
}
```

```json
{
    "error": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
        {
            "field": "password",
            "message": "Password must be at least 8 characters long"
        },
        {
            "field": "password",
            "message": "Password must contain at least one lowercase letter, one uppercase letter, and one number"
        }
    ]
}
```

```json
{
    "error": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
        {
            "field": "org",
            "message": "Required"
        }
    ]
}
```

{% endtab %}

{% tab title="500: Internal Server Error" %}

```json
{ 
    error: "Internal Server Error",
    code: "INTERNAL_SERVER_ERROR",
}
```

{% endtab %}
{% endtabs %}

#### Sample Request

```bash
curl --location '{{URL}}/user/signup' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "testuser@example.com",
  "password": "TestPass123",
  "org": "Test Organization",
  "scope": {
    "ethereum": {
      "validator_addresses": ["0x7e254f0f55e24b8a6995567241618f750d0d94f2cf49b36703869779d2ee4327"],
      "delegator_addresses": ["0xfaiojf923h2i.....", "0x329hipnasfnweufaw....."]
    }
  }
}'
```

***

## Create API key&#x20;

<mark style="color:green;">`POST`</mark> `/user/api-keys`

Send a request to generate a new API key.&#x20;

#### Headers

| Name                                            | Type       | Description                   |
| ----------------------------------------------- | ---------- | ----------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Basic Auth | Base64 encoded email:password |

#### Request Body

```json
{
  "label": "Test API Key"
}
```

| Name                                    | Type   | Description   |
| --------------------------------------- | ------ | ------------- |
| label<mark style="color:red;">\*</mark> | String | API Key Label |

{% tabs %}
{% tab title="201: Created " %}

```javascript
{
    "keyId": "68c0f941ac35dcc2130a00aX",
    "label": "Test API Key",
    "apiKey": "luga-f1cd0029-a256-b234-c9e1-41233a260ea7"
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
    error: "Invalid JSON payload",
    code: "INVALID_JSON"
}
```

```json
{
    "error": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
        {
            "field": "label",
            "message": "Required"
        }
    ]
}
```

```json
{
    "error": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
        {
            "field": "label",
            "message": "Label is too long"
        }
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
    "error": "Basic authentication required",
    "code": "MISSING_BASIC_AUTH"
}
```

```json
{
    "error": "Invalid basic authentication format",
    "code": "INVALID_BASIC_AUTH"
}
```

```json
{
    "error": "Invalid email or password",
    "code": "INVALID_CREDENTIALS"
}
```

{% endtab %}

{% tab title="500: Internal Server Error" %}

```json
{ 
    error: "Internal Server Error",
    code: "INTERNAL_SERVER_ERROR",
}
```

{% endtab %}
{% endtabs %}

#### Sample Request

```bash
curl --location '{{URL}}/user/api-keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdHVzZXXAXuhbXBsZS5jb206GGVzdFBhc3MxMjM=' \
--data '{
  "label": "Test API Key"
}'
```

***

## List API keys

<mark style="color:blue;">`GET`</mark> `/user/api-keys`

List all currently active API Keys.

#### Headers

| Name                                            | Type       | Description                   |
| ----------------------------------------------- | ---------- | ----------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Basic Auth | Base64 encoded email:password |

{% tabs %}
{% tab title="201: Created " %}

```javascript
{
    "keys": [
        {
            "keyId": "68c0f9413c35d9c2140a00a7",
            "label": "Test API Key",
            "createdAt": "2024-09-10T04:06:25.693Z"
        },
        {
            "keyId": "68c0fa9c3c48d9x2140a00ad",
            "label": "Test API Key 1",
            "createdAt": "2024-08-12T04:12:12.131Z"
        },
        {
            "keyId": "68c0fbed3c98d7y2140x00bb",
            "label": "Test API Key 2",
            "createdAt": "2025-01-01T04:17:49.258Z"
        },
        {
            "keyId": "68c0fbfa3c35d9c2140a00c5",
            "label": "Test API Key 3",
            "createdAt": "2025-05-04T04:18:02.692Z"
        },
        {
            "keyId": "68c0fc073c35d9c2140a00d1",
            "label": "Test API Key 4",
            "createdAt": "2025-09-10T04:18:15.306Z"
        }
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
    "error": "Basic authentication required",
    "code": "MISSING_BASIC_AUTH"
}
```

```json
{
    "error": "Invalid basic authentication format",
    "code": "INVALID_BASIC_AUTH"
}
```

```json
{
    "error": "Invalid email or password",
    "code": "INVALID_CREDENTIALS"
}
```

{% endtab %}

{% tab title="500: Internal Server Error" %}

```json
{ 
    error: "Internal Server Error",
    code: "INTERNAL_SERVER_ERROR",
}
```

{% endtab %}
{% endtabs %}

#### Sample Request

```bash
curl --location '{{URL}}/user/api-keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdHVzZXXAXuhbXBsZS5jb206GGVzdFBhc3MxMjM='
```

***

## Revoke API key

<mark style="color:$danger;">`DEL`</mark> `/user/api-keys/{{`<mark style="color:orange;">`keyId`</mark>`}}`

Revoke an API Key

#### Headers

| Name                                            | Type       | Description                   |
| ----------------------------------------------- | ---------- | ----------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Basic Auth | Base64 encoded email:password |

{% tabs %}
{% tab title="204: No Content" %}

> If you receive a 204 No Content status, it means that the key has successfully been revoked.
> {% endtab %}

{% tab title="400 : Bad Request" %}

```json
{
    "error": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
        {
            "field": "keyId",
            "message": "Invalid API key ID format"
        }
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
    "error": "Basic authentication required",
    "code": "MISSING_BASIC_AUTH"
}
```

```json
{
    "error": "Invalid basic authentication format",
    "code": "INVALID_BASIC_AUTH"
}
```

```json
{
    "error": "Invalid email or password",
    "code": "INVALID_CREDENTIALS"
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
    "error": "API key not found or does not belong to user",
    "code": "API_KEY_NOT_FOUND"
}
```

{% endtab %}

{% tab title="500: Internal Server Error" %}

```json
{ 
    error: "Internal Server Error",
    code: "INTERNAL_SERVER_ERROR",
}
```

{% endtab %}
{% endtabs %}

#### Sample Request

```bash
curl --location '{{URL}}/user/api-keys/{{keyId}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdHVzZXXAXuhbXBsZS5jb206GGVzdFBhc3MxMjM='
```

***