chirpstack/api/python/proto/chirpstack-api/api/tenant.proto

syntax = "proto3";

package api;

option go_package = "github.com/chirpstack/chirpstack/api/go/v4/api";
option java_package = "io.chirpstack.api";
option java_multiple_files = true;
option java_outer_classname = "TenantProto";
option csharp_namespace = "Chirpstack.Api";

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

// TenantService is the service providing API methods for managing tenants.
service TenantService {
	// Create a new tenant.
    rpc Create(CreateTenantRequest) returns (CreateTenantResponse) {
        option(google.api.http) = {
            post: "/api/tenants"
            body: "*"
        };
    }

	// Get the tenant for the given ID.
    rpc Get(GetTenantRequest) returns (GetTenantResponse) {
        option(google.api.http) = {
            get: "/api/tenants/{id}"
        };
    }

    // Update the given tenant.
    rpc Update(UpdateTenantRequest) returns (google.protobuf.Empty) {
        option(google.api.http) = {
            put: "/api/tenants/{tenant.id}"
            body: "*"
        };
    }

    // Delete the tenant with the given ID.
    rpc Delete(DeleteTenantRequest) returns (google.protobuf.Empty) {
        option(google.api.http) = {
            delete: "/api/tenants/{id}"
        };
    }

    // Get the list of tenants.
    rpc List(ListTenantsRequest) returns (ListTenantsResponse) {
        option(google.api.http) = {
            get: "/api/tenants"
        };
    }

    // Add an user to the tenant.
    // Note: the user must already exist.
    rpc AddUser(AddTenantUserRequest) returns (google.protobuf.Empty) {
        option(google.api.http) = {
            post: "/api/tenants/{tenant_user.tenant_id}/users"
            body: "*"
        };
    }

    // Get the the tenant user for the given tenant and user IDs.
    rpc GetUser(GetTenantUserRequest) returns (GetTenantUserResponse) {
        option(google.api.http) = {
            get: "/api/tenants/{tenant_id}/users/{user_id}"
        };
    }

    // Update the given tenant user.
    rpc UpdateUser(UpdateTenantUserRequest) returns (google.protobuf.Empty) {
        option(google.api.http) = {
            put: "/api/tenants/{tenant_user.tenant_id}/users/{tenant_user.user_id}"
            body: "*"
        };
    }

    // Delete the given tenant user.
    rpc DeleteUser(DeleteTenantUserRequest) returns (google.protobuf.Empty) {
        option(google.api.http) = {
            delete: "/api/tenants/{tenant_id}/users/{user_id}"
        };
    }

    // Get the list of tenant users.
    rpc ListUsers(ListTenantUsersRequest) returns (ListTenantUsersResponse) {
        option(google.api.http) = {
            get: "/api/tenants/{tenant_id}/users"
        };
    }
}

message Tenant {
	// Tenant ID (UUID).
    // Note: this value will be automatically generated on create.
	string id = 1;

	// Tenant name,
	string name = 2;

    // Tenant description.
    string description = 3;

	// Can the tenant create and "own" Gateways?
	bool can_have_gateways = 4;

    // Max. gateway count for tenant.
    // When set to 0, the tenant can have unlimited gateways.
    uint32 max_gateway_count = 5;

    // Max. device count for tenant.
    // When set to 0, the tenant can have unlimited devices.
    uint32 max_device_count = 6;

    // Private gateways (uplink).
    // If enabled, then uplink messages will not be shared with other tenants.
    bool private_gateways_up = 7;

    // Private gateways (downlink).
    // If enabled, then other tenants will not be able to schedule downlink
    // messages through the gateways of this tenant. For example, in case you
    // do want to share uplinks with other tenants (private_gateways_up=false),
    // but you want to prevent other tenants from using gateway airtime.
    bool private_gateways_down = 8;
}

message TenantListItem {
    // Tenant ID (UUID).
    string id = 1;

	// Created at timestamp.
	google.protobuf.Timestamp created_at = 2;

	// Last update timestamp.
	google.protobuf.Timestamp updated_at = 3;

    // Tenant name.
    string name = 4;

	// Can the tenant create and "own" Gateways?
	bool can_have_gateways = 5;

    // Private gateways (uplink).
    bool private_gateways_up = 6;

    // Private gateways (downlink).
    bool private_gateways_down = 9;

    // Max gateway count.
    // 0 = unlimited.
    uint32 max_gateway_count = 7;

    // Max device count.
    // 0 = unlimited.
    uint32 max_device_count = 8;
}

message CreateTenantRequest {
    // Tenant object to create.
    Tenant tenant = 1;
}

message CreateTenantResponse {
    // Tenant ID.
    string id = 1;
}

message GetTenantRequest {
    // Tenant ID.
    string id = 1;
}

message GetTenantResponse {
    // Tenant object.
    Tenant tenant = 1;

	// Created at timestamp.
	google.protobuf.Timestamp created_at = 2;

	// Last update timestamp.
	google.protobuf.Timestamp updated_at = 3;
}

message UpdateTenantRequest {
    // Tenant object.
    Tenant tenant = 1;
}

message DeleteTenantRequest {
    // Tenant ID.
    string id = 1;
}

message ListTenantsRequest {
    // Max number of tenants to return in the result-set.
    uint32 limit = 1;

    // Offset in the result-set (for pagination).
    uint32 offset = 2;

    // If set, the given string will be used to search on name.
    string search = 3;

    // If set, filters the result set to the tenants of the user.
    // Only global API keys are able to filter by this field.
    string user_id = 4;
}

message ListTenantsResponse {
    // Total number of tenants.
    uint32 total_count = 1;

    // Result-set.
    repeated TenantListItem result = 2;
}

message TenantUser {
	// Tenant ID (UUID).
	string tenant_id = 1;

	// User ID (UUID).
	string user_id = 2;

	// User is admin within the context of the tenant.
    // There is no need to set the is_device_admin and is_gateway_admin flags.
	bool is_admin = 3;

    // User is able to modify device related resources (applications,
    // device-profiles, devices, multicast-groups).
    bool is_device_admin = 4;

    // User is able to modify gateways.
    bool is_gateway_admin = 5;

	// Email (only used on get and when adding a user to a tenant).
	string email = 6;
}

message TenantUserListItem {
	// Tenant ID (UUID).
	string tenant_id = 1;

	// User ID (UUID).
	string user_id = 2;

	// Created at timestamp.
	google.protobuf.Timestamp created_at = 3;

	// Last update timestamp.
	google.protobuf.Timestamp updated_at = 4;

    // Email.
    string email = 5;

	// User is admin within the context of the tenant.
    // There is no need to set the is_device_admin and is_gateway_admin flags.
	bool is_admin = 6;

    // User is able to modify device related resources (applications,
    // device-profiles, devices, multicast-groups).
    bool is_device_admin = 7;

    // User is able to modify gateways.
    bool is_gateway_admin = 8;
}

message AddTenantUserRequest {
    // Tenant user object.
    TenantUser tenant_user = 1;
}

message GetTenantUserRequest {
	// Tenant ID (UUID).
	string tenant_id = 1;

	// User ID (UUID).
	string user_id = 2;
}

message GetTenantUserResponse {
    // Tenant user object.
    TenantUser tenant_user = 1;

	// Created at timestamp.
	google.protobuf.Timestamp created_at = 2;

	// Last update timestamp.
	google.protobuf.Timestamp updated_at = 3;
}

message UpdateTenantUserRequest {
    // Tenant user object.
    TenantUser tenant_user = 1;
}

message DeleteTenantUserRequest {
	// Tenant ID (UUID).
	string tenant_id = 1;

	// User ID (UUID).
	string user_id = 2;
}

message ListTenantUsersRequest {
	// Tenant ID (UUID).
	string tenant_id = 1;

    // Max number of tenants to return in the result-set.
    uint32 limit = 2;

    // Offset in the result-set (for pagination).
    uint32 offset = 3;
}

message ListTenantUsersResponse {
    // Total number of tenants.
    uint32 total_count = 1;

    // Result-set.
    repeated TenantUserListItem result = 2;
}