syntax = "proto3";

package einride.saga.extend.auth.v1beta1;

import "einride/iam/v1/annotations.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/timestamp.proto";
import "protoc-gen-openapiv2/options/annotations.proto";

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "Einride Extend: Authentication API"
    version: "v1beta1"
    description:
      "Based on REST principles, with optional support for gRPC, the Einride Extend API enables modern API-based integration to Einride Saga.\n"
      "\n"
      "API design\n"
      "----------\n"
      "\n"
      "The Einride Extend APIs are designed using the [AIP](https://aip.dev) design framework, which means that they are resource-oriented and work like standard [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs.\n"
      "\n"
      "### Resource-oriented design\n"
      "\n"
      "*See also: [AIP-121: Resource-oriented design](https://google.aip.dev/121)*\n"
      "\n"
      "The fundamental building blocks of this API are individually-named resources (nouns) and the relationships and hierarchy that exist between them.\n"
      "\n"
      "A number of standard methods (verbs) provide the semantics for common [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations. Custom methods are available where custom operations are required, such as for cancelling shipments.\n"
      "\n"
      "### Resource names\n"
      "\n"
      "*See also: [AIP-122: Resource names](https://google.aip.dev/122)*\n"
      "\n"
      "This API exposes resources which users are able to create, retrieve, and manipulate. Resources are named: each resource has a unique identifier that users use to reference that resource, and these names are what users should store as the canonical names for the resources.\n"
      "\n"
      "As such, the unique identifier for a resource in this API is called a *resource name*.\n"
      "\n"
      "Protocols\n"
      "---------\n"
      "\n"
      "The Einride Extend APIs support both HTTP and gRPC protocols.\n"
      "\n"
      "### HTTP\n"
      "\n"
      "The Einride Extend APIs are available as RESTful HTTP endpoints.\n"
      "\n"
      "See this document for the OpenAPI specifications, or use the API documentation at [extend.saga.einride.tech](https://extend.saga.einride.tech), where you can also try out the REST APIs and make example requests.\n"
      "\n"
      "### gRPC\n"
      "\n"
      "[gRPC](https://grpc.io) is a high performance, open source universal RPC framework that works across programming languages and platforms.\n"
      "\n"
      "To for more information about using Einride Extend APIs via gRPC, please contact your Einride representative.\n"
      "\n"
      "Authentication\n"
      "---------\n"
      "\n"
      "The Einride Extend use standard [Bearer token authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). When using the HTTP APIs, make sure to always provide the following header in all requests:\n"
      "\n"
      "\n"
      "    Authorization: Bearer <token>\n"
      "\n"
      "\n"
      "Where `<token>` is the authentication token for your integration. \n"
      "\n"
      "\n"
      "Obtain a short-lived authentication token by using the ExchangeSecret API documented below. \n"
      "\n"
      "\n"
      "Please contact your Einride representative to obtain a client ID and client secret for your integration. \n"
      "\n"
      "API address\n"
      "---------\n"
      "\n"
      "The Einride Extend API is available via the following root address:\n"
      "\n"
      "https://api.saga.einride.tech\n"
  }
  schemes: HTTPS
  consumes: "application/json"
  produces: "application/json"
};

// Authentication service.
service AuthenticationService {
  option (google.api.default_host) = "api.saga.einride.tech";

  // Exchange secret for access token.
  rpc ExchangeSecret(ExchangeSecretRequest) returns (ExchangeSecretResponse) {
    option (google.api.http) = {
      post: "/v1beta1/auth:exchangeSecret"
      body: "*"
    };
    option (einride.iam.v1.method_authorization).none = true;
  }
}

// Request to the ExchangeSecret method.
message ExchangeSecretRequest {
  // The client ID.
  //
  // Example: "example"
  string client_id = 1 [
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "The client ID."
      format: "string"
    }
  ];

  // The client secret.
  string client_secret = 2 [
    (google.api.field_behavior) = REQUIRED,
    debug_redact = true,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "The client secret."
      format: "password"
      field_configuration: {path_param_name: "secret"}
    }
  ];
}

// Response from the ExchangeSecret method.
message ExchangeSecretResponse {
  // Access token to pass as a Bearer token in the authorization header
  // on subsequent API calls.
  string access_token = 1 [debug_redact = true];

  // Expire time of the access token.
  google.protobuf.Timestamp expire_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}