dex/api/v2/api.proto

syntax = "proto3";
option java_package = "com.coreos.dex.api";

package api;

// Client represents an OAuth2 client.
message Client {
  string id = 1;
  string secret = 2;
  repeated string redirect_uris = 3;
  repeated string trusted_peers = 4;
  bool public = 5;
  string name = 6;
  string logo_url = 7;
}

// CreateClientReq is a request to make a client.
message CreateClientReq {
  Client client = 1;
}

// CreateClientResp returns the response from creating a client.
message CreateClientResp {
  bool already_exists = 1;
  Client client = 2; 
}

// DeleteClientReq is a request to delete a client.
message DeleteClientReq {
  // The ID of the client.
  string id = 1;
}

// DeleteClientResp determines if the client is deleted successfully. 
message DeleteClientResp {
  bool not_found = 1;
}

// UpdateClientReq is a request to update an existing client.
message UpdateClientReq {
    string id = 1;
    repeated string redirect_uris = 2;
    repeated string trusted_peers = 3;
    string name = 4;
    string logo_url = 5;
}

// UpdateClientResp returns the response from updating a client.
message UpdateClientResp {
    bool not_found = 1;
}

// TODO(ericchiang): expand this.

// Password is an email for password mapping managed by the storage.
message Password {
  string email = 1;

  // Currently we do not accept plain text passwords. Could be an option in the future.
  bytes hash = 2;
  string username = 3;
  string user_id = 4;
}

// CreatePasswordReq is a request to make a password.
message CreatePasswordReq {
  Password password = 1;
}

// CreatePasswordResp returns the response from creating a password.
message CreatePasswordResp {
  bool already_exists = 1;
}

// UpdatePasswordReq is a request to modify an existing password.
message UpdatePasswordReq {
  // The email used to lookup the password. This field cannot be modified
  string email = 1;
  bytes new_hash = 2;
  string new_username = 3;
}

// UpdatePasswordResp returns the response from modifying an existing password. 
message UpdatePasswordResp {
  bool not_found = 1;
}

// DeletePasswordReq is a request to delete a password.
message DeletePasswordReq {
  string email = 1;
}

// DeletePasswordResp returns the response from deleting a password. 
message DeletePasswordResp {
  bool not_found = 1;
}

// ListPasswordReq is a request to enumerate passwords.
message ListPasswordReq {}

// ListPasswordResp returns a list of passwords.
message ListPasswordResp {
  repeated Password passwords = 1;
}

// VersionReq is a request to fetch version info.
message VersionReq {}

// VersionResp holds the version info of components.
message VersionResp {
  // Semantic version of the server.
  string server = 1;
  // Numeric version of the API. It increases everytime a new call is added to the API.
  // Clients should use this info to determine if the server supports specific features.
  int32 api = 2;
}

// RefreshTokenRef contains the metadata for a refresh token that is managed by the storage.
message RefreshTokenRef {
  // ID of the refresh token.
  string id = 1;
  string client_id = 2;
  int64 created_at = 5;
  int64 last_used = 6;
}

// ListRefreshReq is a request to enumerate the refresh tokens of a user.
message ListRefreshReq {
  // The "sub" claim returned in the ID Token.
  string user_id = 1;
}

// ListRefreshResp returns a list of refresh tokens for a user.
message ListRefreshResp {
  repeated RefreshTokenRef refresh_tokens = 1;
}

// RevokeRefreshReq is a request to revoke the refresh token of the user-client pair.
message RevokeRefreshReq {
  // The "sub" claim returned in the ID Token.
  string user_id = 1;
  string client_id = 2;
}

// RevokeRefreshResp determines if the refresh token is revoked successfully. 
message RevokeRefreshResp {
  // Set to true is refresh token was not found and token could not be revoked.
  bool not_found = 1;
}

message VerifyPasswordReq {
  string email = 1;
  string password = 2;
}

message VerifyPasswordResp {
  bool verified = 1;
  bool not_found = 2;
}

// Dex represents the dex gRPC service.
service Dex {
  // CreateClient creates a client.
  rpc CreateClient(CreateClientReq) returns (CreateClientResp) {};
  // UpdateClient updates an existing client
  rpc UpdateClient(UpdateClientReq) returns (UpdateClientResp) {};
  // DeleteClient deletes the provided client.
  rpc DeleteClient(DeleteClientReq) returns (DeleteClientResp) {};
  // CreatePassword creates a password.
  rpc CreatePassword(CreatePasswordReq) returns (CreatePasswordResp) {};
  // UpdatePassword modifies existing password.
  rpc UpdatePassword(UpdatePasswordReq) returns (UpdatePasswordResp) {};
  // DeletePassword deletes the password.
  rpc DeletePassword(DeletePasswordReq) returns (DeletePasswordResp) {};
  // ListPassword lists all password entries.
  rpc ListPasswords(ListPasswordReq) returns (ListPasswordResp) {};
  // GetVersion returns version information of the server.
  rpc GetVersion(VersionReq) returns (VersionResp) {};
  // ListRefresh lists all the refresh token entries for a particular user.
  rpc ListRefresh(ListRefreshReq) returns (ListRefreshResp) {};
  // RevokeRefresh revokes the refresh token for the provided user-client pair.
  //
  // Note that each user-client pair can have only one refresh token at a time.
  rpc RevokeRefresh(RevokeRefreshReq) returns (RevokeRefreshResp) {};
  // VerifyPassword returns whether a password matches a hash for a specific email or not.
  rpc VerifyPassword(VerifyPasswordReq) returns (VerifyPasswordResp) {};
}