admin

package
v1.117.0-rc Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 7, 2024 License: AGPL-3.0 Imports: 42 Imported by: 0

README

satellite/admin

Satellite Admin package provides API endpoints for administrative tasks.

Requires setting Authorization header for requests.

NOTE The API has endpoints which are deprecated in favor of using storj-admin, but they are keep it because we have tooling that may use them. The deprecated endpoints are marked with a DEPRECATED in this document.

The deprecated endpoints are not accessible through the Web UI.

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} - DEPRECATED

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} - DEPRECATED

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",
            "publicId": "9551ffef-935c-4d62-9a3b-00d36c411182",
            "name": "Project",
            "description": "Project to store data.",
            "ownerId": "12345678-1234-1234-1234-123456789abc"
        }
    ]
}
GET /api/users/{user-email}/limits - DEPRECATED

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.

Freezes a user account for legal review so no uploads or downloads may occur User status is also set to Legal hold. The user cannot exit this state automatically.

Removes the legal 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 legal frozen state.

PUT /api/users/{user-email}/trial-expiration-freeze

Freezes a user account for trial expiration. In this state, the user cannot upload or download data. The user can exit this state when they upgrade to a paid tier.

DELETE /api/users/{user-email}/trial-expiration-freeze

Removes the trial expiration freeze on a user account, reinstating account limits.

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

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

GET /api/users/deletion/pending

Returns a limited list of users pending deletion and have no unpaid invoices. Required parameters: limit and page.

Example: /api/users/deletion/pending?limit=10&page=1

GET /api/users/deletion/requested-by-user

Returns a CSV of user account emails which were requested for deletion by users themselves. Required parameters: before.

Example: /api/users/deletion/requested-by-user?before=2021-01-01T00:00:00.000Z

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

Sets the account level geofence for the user.

Example request:

{
  "region": "US"
}
DELETE /api/users/{user-email}/geofence - DEPRECATED

Removes the account level geofence for the user.

PATCH /api/users/{user-email}/activate-account/disable-bot-restriction

Disables account bot restrictions by activating the account and restoring its limit values. This is used only for accounts with the PendingBotVerification status.

PATCH /api/users/{user-email}/trial-expiration

Updates account free trial expiration date.

Example request:

{
  "trialExpiration": "2024-06-01T00:00:00.000Z"
}

or

{
  "trialExpiration": null
}
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} - DEPRECATED

Gets the common information about a project.

PUT /api/projects/{project-id} - DEPRECATED

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={value}

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 - DEPRECATED

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).

This endpoint also accepts to receive the information as a form in the request body, that is content type application/x-www-form-urlencoded and the header must be specified, otherwise the server doesn't read the request body.

Using the 0 number means to set them exactly to 0, which is not the same than using the default value. Default values are applied when they are nil. Only the indicated fields support to set the default value to nil using the -1 number.

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

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

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

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

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

Updates rate limit for a project.

Accepts -1 to set to nil.

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

Updates number of buckets limit for a project.

Accepts -1 to set to nil.

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

Updates burst limit for a project.

Accepts -1 to set to nil.

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

Updates number of segments limit for a project.

PUT /api/projects/{project-id}/geofence?region={value}

Updates the geofence configuration for the specified project.

If the project's geofence isn't set yet, this method will set it. If the project's geofence is already set and you want to unset it, you must use the DELETE method.

value must be one of the following EU, EEA, US, DE, or NR.

DELETE /api/projects/{project-id}/geofence

Unset the geofence configuration for the specified project.

If the project's geofence isn't set yet, this method won't return an error and will do nothing.

Bucket Management

This set of APIs provide administrative functionality over bucket functionality.

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

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} - DEPRECATED

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 - DEPRECATED

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

Project API Keys Management
GET /api/apikeys/{api-key}

Gets information on the given API key.

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/{api-key}

Deletes the given API key.

REST API Keys Management
POST /api/restkeys/{user-email}

Create a REST API key for the user's account associated to the indicated e-mail.

An example of a required request body:

{
    "expiration": "30d20h"
}

If expiration is empty, the default expiration is applied. Otherwise, the expiration parameter must have some non-negative value according to https://pkg.go.dev/time#ParseDuration.

PUT /api/restkeys/{api-key}/revoke

Revoke the indicated REST API key.

Documentation

Overview

Package admin implements administrative endpoints for satellite.

Index

Constants

View Source 
const (
	// UnauthorizedNotInGroup - message for when api user is not part of a required access group.
	UnauthorizedNotInGroup = "User must be a member of one of these groups to conduct this operation: %s"
	// AuthorizationNotEnabled - message for when authorization is disabled.
	AuthorizationNotEnabled = "Authorization not enabled."

	// BackOfficePathPrefix is the path prefix used for the back office router.
	BackOfficePathPrefix = "/back-office"
)

Variables

View Source 
var Assets fs.FS = emptyfs.FS{}

Assets contains either the built admin/back-office/ui or it is nil.

View Source 
var Error = errs.Class("admin")

Error is default error class for admin package.

Functions

This section is empty.

Types

type Config 

type Config struct {
	Address          string `` /* 149-byte string literal not displayed */
	StaticDir        string `` /* 149-byte string literal not displayed */
	AllowedOauthHost string `help:"the oauth host allowed to bypass token authentication."`
	Groups           Groups

	AuthorizationToken string `internal:"true"`
	BackOffice         backoffice.Config
}

Config defines configuration for debug server.

type DB added in v0.34.1 

type DB interface {
	// ProjectAccounting returns database for storing information about project data use
	ProjectAccounting() accounting.ProjectAccounting
	// Console returns database for satellite console
	Console() console.DB
	// OIDC returns the database for OIDC and OAuth information.
	OIDC() oidc.DB
	// StripeCoinPayments returns database for satellite stripe coin payments
	StripeCoinPayments() stripe.DB
	// Buckets returns database for buckets metainfo.
	Buckets() buckets.DB
	// Attribution returns database for value attribution.
	Attribution() attribution.DB
}

DB is databases needed for the admin server.

type Groups added in v1.74.1 

type Groups struct {
	LimitUpdate string `help:"the group which is only allowed to update user and project limits and freeze and unfreeze accounts."`
}

Groups defines permission groups.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server provides endpoints for administrative tasks.

func NewServer 

func NewServer(
	log *zap.Logger,
	listener net.Listener,
	db DB,
	metabaseDB *metabase.DB,
	buckets *buckets.Service,
	restKeys *restkeys.Service,
	freezeAccounts *console.AccountFreezeService,
	analyticsService *analytics.Service,
	accounts payments.Accounts,
	backOfficeService *backoffice.Service,
	console consoleweb.Config,
	config Config,
) *Server

NewServer returns a new administration Server.

func (*Server) Close 

func (server *Server) Close() error

Close closes server and underlying listener.

func (*Server) Run 

func (server *Server) Run(ctx context.Context) error

Run starts the admin endpoint.

func (*Server) SetAllowedOauthHost added in v1.78.1 

func (server *Server) SetAllowedOauthHost(host string)

SetAllowedOauthHost allows tests to set which address to recognize as belonging to the OAuth proxy.

func (*Server) SetNow added in v1.13.1 

func (server *Server) SetNow(nowFn func() time.Time)

SetNow allows tests to have the server act as if the current time is whatever they want.

Source Files

View all Source files

Directories

Path Synopsis
See LICENSE for copying information.
 See LICENSE for copying information.
gen
Package main defines the satellite administration API through the API generator and generates source code of the API server handlers and clients and the documentation markdown document.
 Package main defines the satellite administration API through the API generator and generates source code of the API server handlers and clients and the documentation markdown document.
ui

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.