History

Ivan Fraixedes ae945b993a satellite/admin: Create separate server for new back-office Create a separate server for implementing the new satellite administration web app. This server is in a new package that will implement all the functionality for the new satellite administration back-end and when it be completed with all the functionality that the current one offer, it will replace it. For now, the new server only exposes the static assets as they were exposed by the current server. A main sub-package is added with an example endpoint to scaffold where we'll define the API through the API generator and to locate the several generated files. Change-Id: I172c43b2c180553876ef7ce137cc778b94723451		2023-11-07 15:31:01 +01:00
..
back-office	satellite/admin: Create separate server for new back-office	2023-11-07 15:31:01 +01:00
ui	satellite/admin: list users pending deletion	2023-10-30 19:11:16 +00:00
apikeys_test.go	satellite/admin: add owner full name on /api/apikeys/{apikey} endpoint	2023-06-28 16:01:15 +12:00
apikeys.go	satellite/admin: support more options for passing project ID	2023-09-07 08:53:41 +00:00
bucket_test.go	satellite/admin: introduce new placement rule	2023-06-05 13:34:26 +00:00
bucket_testplanet_test.go	satellite/buckets: move Bucket definition	2023-04-13 17:55:40 -04:00
bucket.go	satellite/admin: add missing test assert to project geofence tests	2023-10-05 18:21:48 +13:00
common.go	satellite/admin: support more options for passing project ID	2023-09-07 08:53:41 +00:00
oauthclients_testplanet_test.go	all: fix linting issues	2022-03-21 15:26:42 +00:00
oauthclients.go	satellite/oidc: move oidc into common package	2022-02-08 09:46:54 -06:00
project_test.go	satellite/admin: return burst limit in API response	2023-09-27 22:11:00 +00:00
project_testplanet_test.go	satellite/admin: add missing test assert to project geofence tests	2023-10-05 18:21:48 +13:00
project.go	satellite/{admin,console,satellitedb}: fix geofence removal	2023-10-04 16:14:29 +00:00
README.md	satellite/admin: list users pending deletion	2023-10-30 19:11:16 +00:00
restkeys_test.go	all: fix deprecated ioutil commands	2022-10-11 15:27:29 +00:00
restkeys.go	all: fix deprecated ioutil commands	2022-10-11 15:27:29 +00:00
server_test.go	satellite/admin: Create separate server for new back-office	2023-11-07 15:31:01 +01:00
server.go	satellite/admin: Create separate server for new back-office	2023-11-07 15:31:01 +01:00
testutils_test.go	all: fix deprecated ioutil commands	2022-10-11 15:27:29 +00:00
user_test.go	satellite/admin: add endpoints to violation freeze/unfreeze users	2023-10-13 10:43:44 +00:00
user.go	satellite/admin: list users pending deletion	2023-10-30 19:11:16 +00:00

README.md

satellite/admin

Satellite Admin package provides API endpoints for administrative tasks.

Requires setting Authorization header for requests.

satellite/admin
- API design
  - Successful responses
  - Error responses
- API Endpoints

API design

Successful responses

For non-get requests (PUT, POST, DELETE), endpoints should return an empty response body on success. GET requests can return a non-empty body for the resource that we're interacting with.

Error responses

When an API endpoint returns a client error (status code 4XX) it returns a JSON error response which contains 2 fields:

error: The error message.
detail (may be empty): Some detail about the returned error.

Example:

{
  "error": "usage for the current month exists",
  "detail": ""
}

API Endpoints

User Management

POST /api/users

Adds a new user.

An example of a required request body:

{
    "email": "alice@mail.test",
    "fullName": "Alice Test",
    "password": "password"
}

A successful response body:

{
    "id":           "12345678-1234-1234-1234-123456789abc",
    "email":        "alice@mail.test",
    "fullName":     "Alice Test",
    "shortName":    "",
    "passwordHash": ""
}

PUT /api/users/{user-email}

Updates the details of existing user found by its email.

Some example request bodies:

{
    "email": "alice+2@mail.test"
}

{
    "email": "alice+2@mail.test",
    "shortName": "myNickName"
}

{
    "projectLimit": 200
}

GET /api/users/{user-email}

This endpoint returns information about user and their projects.

A successful response body:

{
    "user":{
        "id": "12345678-1234-1234-1234-123456789abc",
        "fullName": "Alice Bob",
        "email":"alice@example.test",
        "projectLimit": 10
    },
    "projects":[
        {
            "id": "abcabcab-1234-abcd-abcd-abecdefedcab",
            "name": "Project",
            "description": "Project to store data.",
            "ownerId": "12345678-1234-1234-1234-123456789abc"
        }
    ]
}

GET /api/users/{user-email}/limits

This endpoint returns information about users limits.

DELETE /api/users/{user-email}

Deletes the user.

PUT /api/users/{user-email}/limits

Updates the limits of the user and user's existing project(s) limits found by its email.

DELETE /api/users/{user-email}/mfa

Disables the user's mfa.

PUT /api/users/{user-email}/billing-freeze

Freezes a user account so no uploads or downloads may occur. This is a billing freeze the user can exit automatically by paying their invoice.

DELETE /api/users/{user-email}/billing-freeze

Unfreezes a previously billing frozen user account so uploads and downloads may resume.

PUT /api/users/{user-email}/violation-freeze

Freezes a user account for violation so no uploads or downloads may occur User status is also set to Pending Deletion. The user cannot exit this state automatically.

DELETE /api/users/{user-email}/violation-freeze

Removes the violation freeze on a user account so uploads and downloads may resume. User status is set back to Active. This is the only way to exit the violation frozen state.

DELETE /api/users/{user-email}/billing-warning

Removes the billing warning status from a user's account.

GET /api/users/pending-deletion

Returns a limited list of users pending deletion and have no unpaid invoices. Required parameters: limit and page. Example: /api/users/pending-deletion?limit=10&page=1

PATCH /api/users/{user-email}/geofence

Sets the account level geofence for the user.

Example request:

{
  "region": "US"
}

DELETE /api/users/{user-email}/geofence

Removes the account level geofence for the user.

OAuth Client Management

Manages oauth clients known to the Satellite.

POST /api/oauth/clients

Create a new OAuthClient. A client ID and clientSecret will be returned upon creation.

Example request:

{
  "id": "uuid-of-the-client",
  "secret": "shh-this-should-be-kept-safe",
  "redirectURL": "http://localhost:8888/oauth/storj/callback",
  "userID": "uuid-of-the-owner",
  "appName": "Example App",
  "appLogoURL": "http://localhost:8888/logo.png"
}

PUT /api/oauth/clients/{id}

Update an existing oauth client.

Example request:

{
  "redirectURL": "http://localhost:8888/oauth/storj/callback",
  "appName": "Example App",
  "appLogoURL": "http://localhost:8888/logo.png"
}

DELETE /api/oauth/clients/{id}

Delete the identified oauth client.

Project Management

POST /api/projects

Adds a project for specific user.

An example of a required request body:

{
    "ownerId": "ca7aa0fb-442a-4d4e-aa36-a49abddae837",
    "projectName": "My Second Project"
}

A successful response body:

{
    "projectId": "ca7aa0fb-442a-4d4e-aa36-a49abddae646"
}

GET /api/projects/{project-id}

Gets the common information about a project.

PUT /api/projects/{project-id}

Updates project name or description.

{
    "projectName": "My new Project Name",
    "description": "My new awesome description!"
}

DELETE /api/projects/{project-id}

Deletes the project.

GET /api/projects/{project}/apikeys

Get the list of the API keys of a specific project.

A successful response body:

[
    {
        "id": "b6988bd2-8d21-4bee-91ac-a3445bf38180",
        "ownerId": "ca7aa0fb-442a-4d4e-aa36-a49abddae837",
        "name": "mine",
        "partnerID": "a9d3b7ee-17da-4848-bb0e-1f64cf45af18",
        "createdAt": "2020-05-19T00:34:13.265761+02:00"
    },
    {
        "id": "f9f887c1-b178-4eb8-b669-14379c5a97ca",
        "ownerId": "3eb45ae9-822a-470e-a51a-9144dedda63e",
        "name": "family",
        "partnerID": "",
        "createdAt": "2020-02-20T15:34:24.265761+02:00"
    }
]

POST /api/projects/{project}/apikeys

Adds an apikey for specific project.

An example of a required request body:

{
    "name": "My first API Key"
}

Note: Additionally you can specify partnerId to associate it with the given apikey. If you specify it, it has to be a valid uuid and not an empty string.

A successful response body:

{
    "apikey": "13YqdMKxAVBamFsS6Mj3sCQ35HySoA254xmXCCQGJqffLnqrBaQDoTcCiCfbkaFPNewHT79rrFC5XRm4Z2PENtRSBDVNz8zcjS28W5v"
}

DELETE /api/projects/{project}/apikeys/{name}

Deletes the given apikey by its name.

GET /api/projects/{project-id}/usage

This endpoint returns whether the project has outstanding usage or not.

A project with not usage returns status code 200 and {"result":"no project usage exist"}. Otherwise, it returns status code 409 with a JSON error.{"error":"usage for current month exists""}.

GET /api/projects/{project-id}/limit

This endpoint returns information about project limits.

A successful response body:

{
  "usage": {
    "amount": "1.0 TB",
    "bytes": 1000000000000
  },
  "bandwidth": {
    "amount": "1.0 TB",
    "bytes": 1000000000000
  },
  "rate": {
    "rps": 0
  },
  "maxBuckets": 1000,
  "maxSegments": 1000000000
}

Update limits

You can update the different limits with one single request just adding the various query parameters (e.g. usage=5000000&bandwidth=9000000)

POST /api/projects/{project-id}/limit?usage={value}

Updates usage limit for a project. The value must be in bytes.

POST /api/projects/{project-id}/limit?bandwidth={value}

Updates bandwidth limit for a project. The value must be in bytes.

POST /api/projects/{project-id}/limit?rate={value}

Updates rate limit for a project.

POST /api/projects/{project-id}/limit?buckets={value}

Updates number of buckets limit for a project.

POST /api/projects/{project-id}/limit?burst={value}

Updates burst limit for a project.

POST /api/projects/{project-id}/limit?segments={value}

Updates number of segments limit for a project.

Bucket Management

This set of APIs provide administrative functionality over bucket functionality.

GET /api/projects/{project-id}/buckets/{bucket-name}

Returns all the information of the specified bucket.

Geofencing

Manage geofencing capabilities for a given bucket.

POST /api/projects/{project-id}/buckets/{bucket-name}/geofence?region={value}

Enables the geofencing configuration for the specified bucket. The bucket MUST be empty in order for this to work. Valid values for the region parameter are:

EU - restrict placement to data nodes that reside in the European Union
EEA - restrict placement to data nodes that reside in the European Economic Area
US - restricts placement to data nodes in the United States
DE - restricts placement to data nodes in Germany

DELETE /api/projects/{project-id}/buckets/{bucket-name}/geofence

Removes the geofencing configuration for the specified bucket. The bucket MUST be empty in order for this to work.

APIKey Management

GET /api/apikeys/{apikey}

Gets information on the given apikey.

A successful response body:

{
  "api_key": {
    "id": "12345678-1234-1234-1234-123456789abc",
    "name": "my key",
    "createdAt": "2020-05-19T00:34:13.265761+02:00"
  },
  "project": {
    "id": "12345678-1234-1234-1234-123456789abc",
    "name": "My Project"
  },
  "owner": {
    "id": "12345678-1234-1234-1234-123456789abc",
    "fullName": "test user",
    "email": "bob@example.test",
    "paidTier": true
  }
}

DELETE /api/apikeys/{apikey}

Deletes the given apikey.