openEO Account Management API

openapi: 3.2.0
info:
  title: openEO Account Management API
  version: 1.3.0
  description: The openEO API specification for interoperable cloud-based processing of large Earth observation datasets.
  contact:
    name: openEO Project Steering Committee
    url: https://openeo.org
    email: openeo.psc@uni-muenster.de
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://openeo.example/api/{version}
  description: The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a *recommendation* only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
  variables:
    version:
      default: v1
      description: 'API versioning is RECOMMENDED. As the openEO API is following

        [SemVer](https://semver.org/) only the **major** part of the version

        numbers SHOULD be used for API versioning in the URL. To make clear

        that it is a version number, it is RECOMMENDED to add the prefix `v`.


        Example: API version `1.2.3` is recommended to use `v1`.


        The reason to only consider the major part is that backward-incompatible

        changes are introduced by major changes only. All changes from minor

        and patch releases can usually be integrated without breakages and thus

        a change in the URL is not really needed.


        The version number in the URL MUST not be used by the clients to detect

        the version number of the API. Use the version number returned in the

        property `api_version` from `GET /` instead.'
tags:
- name: Account Management
  description: The following endpoints handle user profiles, accounting and authentication.
paths:
  /credentials/oidc:
    get:
      summary: OpenID Connect authentication
      operationId: authenticate-oidc
      description: 'Lists the supported OpenID Connect

        providers (OP). OpenID Connect Providers MUST support OpenID Connect

        Discovery.


        It is highly RECOMMENDED to implement OpenID Connect for public services

        in favor of Basic authentication.


        openEO clients MUST use the **access token** as part of the Bearer token

        for authorization in subsequent API calls (see also the information

        about Bearer tokens in this document). Clients MUST NOT use the id token

        or the authorization code.


        Back-ends MAY request user information (including Claims)

        from the OpenID Connect Userinfo endpoint

        using the access token (without the prefix described above). Therefore,

        both openEO client and openEO back-end are relying parties (clients) to

        the OpenID Connect Provider.'
      tags:
      - Account Management
      security:
      - {}
      responses:
        '200':
          description: Lists the OpenID Connect Providers.
          content:
            application/json:
              schema:
                title: OpenID Connect Providers
                type: object
                required:
                - providers
                properties:
                  providers:
                    type: array
                    description: The first provider in this list is the default provider for authentication. Clients can either pre-select or directly use the default provider for authentication if the user does not specify a specific value.
                    minItems: 1
                    items:
                      title: OpenID Connect Provider
                      type: object
                      required:
                      - id
                      - issuer
                      - title
                      properties:
                        id:
                          type: string
                          description: 'A per-back-end **unique** identifier for the OpenID Connect provider.


                            Is used as prefix for the openEO token.'
                          pattern: '[\d\w]{1,20}'
                        issuer:
                          type: string
                          format: uri
                          description: 'The [issuer location](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)

                            (also referred to as ''authority'' in some client libraries) is the URL of the

                            OpenID Connect provider, which conforms to a set of rules:


                            1. After appending `/.well-known/openid-configuration` to the URL, a

                            [HTTP/1.1 GET

                            request](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest)

                            to the concatenated URL MUST return a [OpenID Connect Discovery Configuration

                            Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse).

                            The response provides all information required to authenticate using

                            OpenID Connect.


                            2. The URL MUST NOT contain a terminating forward slash `/`.'
                          example: https://accounts.google.com
                        scopes:
                          type: array
                          description: 'A list of OpenID Connect scopes that the client MUST at least include when requesting authorization. Clients MAY add additional scopes such as the `offline_access` scope to retrieve a refresh token.

                            If scopes are specified, the list MUST at least contain the `openid` scope.'
                          items:
                            type: string
                        title:
                          type: string
                          description: The name that is publicly shown in clients for this OpenID Connect provider.
                        description:
                          type: string
                          format: commonmark
                          description: 'A description that explains how the authentication procedure works.


                            It should make clear how to register and get credentials. This should

                            include instruction on setting up `client_id`, `client_secret` and `redirect_uri`.


                            [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich

                            text representation.'
                        default_clients:
                          title: Default OpenID Connect Clients
                          type: array
                          description: 'List of default OpenID Connect clients that can be used by an openEO client

                            for OpenID Connect based authentication.


                            A default OpenID Connect client is managed by the back-end implementer.

                            It MUST be configured to be usable without a client secret,

                            which limits its applicability to OpenID Connect grant types like

                            "Authorization Code Grant with PKCE" and "Device Authorization Grant with PKCE"


                            A default OpenID Connect client is provided without availability guarantees.

                            The back-end implementer CAN revoke, reset or update it any time.

                            As such, openEO clients SHOULD NOT store or cache default OpenID Connect client information

                            for long term usage.

                            A default OpenID Connect client is intended to simplify authentication for novice users.

                            Setting up a dedicated OpenID Connect client is RECOMMENDED for production-ready back-ends.'
                          uniqueItems: true
                          items:
                            title: Default OpenID Connect Client
                            type: object
                            required:
                            - id
                            - grant_types
                            properties:
                              id:
                                type: string
                                description: The OpenID Connect Client ID to be used in the authentication procedure.
                              grant_types:
                                type: array
                                description: 'List of authorization grant types (flows) supported by the OpenID Connect client.

                                  A grant type descriptor consist of a OAuth 2.0 grant type,

                                  with an additional `+pkce` suffix when the grant type should be used with

                                  the PKCE extension as defined in [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636.html).


                                  Allowed values:

                                  - `implicit`: Implicit Grant as specified in [RFC 6749, sec. 1.3.2](https://www.rfc-editor.org/rfc/rfc6749.html#section-1.3.2)

                                  - `authorization_code` / `authorization_code+pkce`: Authorization Code Grant as specified in [RFC 6749, sec. 1.3.1](https://www.rfc-editor.org/rfc/rfc6749.html#section-1.3.1), with or without PKCE extension.

                                  - `urn:ietf:params:oauth:grant-type:device_code` / `urn:ietf:params:oauth:grant-type:device_code+pkce`: Device Authorization Grant (aka Device Code Flow) as specified in [RFC 8628](https://www.rfc-editor.org/rfc/rfc8628.html), with or without PKCE extension. Note that the combination of this grant with the PKCE extension is *not standardized* yet.

                                  - `refresh_token`: Refresh Token as specified in [RFC 6749, sec. 1.5](https://www.rfc-editor.org/rfc/rfc6749.html#section-1.5)'
                                minItems: 1
                                uniqueItems: true
                                items:
                                  type: string
                                  enum:
                                  - implicit
                                  - authorization_code
                                  - authorization_code+pkce
                                  - urn:ietf:params:oauth:grant-type:device_code
                                  - urn:ietf:params:oauth:grant-type:device_code+pkce
                                  - refresh_token
                              redirect_urls:
                                type: array
                                description: 'List of redirect URLs that are whitelisted by the OpenID Connect client.

                                  Redirect URLs MUST be provided when the OpenID Connect client supports

                                  the Implicit Grant or the Authorization Code Grant (with or without PKCE extension).'
                                uniqueItems: true
                                items:
                                  type: string
                                  format: uri
                        authorization_parameters:
                          type: object
                          description: 'Additional parameters that an openEO client MUST include when requesting the authorization endpoint.

                            This can be used to enforce specific

                            [request parameters such as `prompt`](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).'
                          example:
                            prompt: consent
                            access_type: offline
                        links:
                          type: array
                          description: 'Links related to this provider, for example a

                            help page or a page to register a new user account.


                            For relation types see the lists of

                            [common relation types in openEO](#section/API-Principles/Web-Linking).'
                          items:
                            $ref: '#/components/schemas/link'
              example:
                providers:
                - id: egi
                  issuer: https://aai.egi.eu/oidc
                  title: EGI (default)
                  description: Login with your academic account.
                  scopes:
                  - openid
                  - profile
                  - email
                  default_clients:
                  - id: KStcUzD5AIUA
                    grant_types:
                    - implicit
                    - authorization_code+pkce
                    - urn:ietf:params:oauth:grant-type:device_code+pkce
                    - refresh_token
                    redirect_urls:
                    - https://editor.openeo.org/
                - id: google
                  issuer: https://accounts.google.com
                  title: Google
                  description: Login with your Google Account.
                  scopes:
                  - openid
                  - profile
                  - email
                  - earthengine
                  authorization_parameters:
                    access_type: offline
                - id: ms
                  issuer: https://login.microsoftonline.com/example-tenant/v2.0
                  title: Microsoft
                  description: Login with your Microsoft or Skype Account.
                  scopes: []
        4XX:
          $ref: '#/components/responses/client_error_auth'
        5XX:
          $ref: '#/components/responses/server_error'
  /credentials/basic:
    get:
      summary: HTTP Basic authentication
      operationId: authenticate-basic
      description: 'Checks the credentials provided through HTTP Basic Authentication

        according to RFC 7617 and

        returns an access token in exchange for providing valid credentials.


        The credentials (username and password) MUST be sent in the HTTP header

        `Authorization` with type `Basic` and the Base64 encoded string

        consisting of username and password separated by a double colon `:`. The

        header would look as follows for username `user` and password `pw`:

        `Authorization: Basic dXNlcjpwdw==`.


        The access token has to be used in the Bearer token for authorization in

        subsequent API calls (see also the information about Bearer tokens in

        this document).


        It is RECOMMENDED to implement this authentication method for non-public

        services only.'
      tags:
      - Account Management
      security:
      - Basic: []
      responses:
        '200':
          description: Credentials are correct and authentication succeeded.
          content:
            application/json:
              schema:
                title: HTTP Basic Access Token
                type: object
                required:
                - access_token
                properties:
                  access_token:
                    description: The access token to be used in the Bearer token for authorization in subsequent API calls (without the custom `basic//` prefix).
                    type: string
                    example: b34ba2bdf9ac9ee1
        4XX:
          $ref: '#/components/responses/client_error_auth'
        5XX:
          $ref: '#/components/responses/server_error'
  /me:
    get:
      summary: Information about the authenticated user
      operationId: describe-account
      description: 'Lists information about the authenticated user such as the user id.

        The endpoint MAY return the disk quota available to the user. The endpoint MAY also return links related to user management and the user profile, e.g. where payments are handled or the user profile could be edited.

        For back-ends that involve accounting, this service MAY also return the currently available money or credits in the currency the back-end is working with.

        This endpoint MAY be extended to fulfil the specification of the OpenID Connect UserInfo Endpoint.'
      tags:
      - Account Management
      security:
      - Bearer: []
      responses:
        '200':
          description: Information about the logged in user.
          content:
            application/json:
              schema:
                title: User Data
                description: Holds user information. If no budget or storage limit applies to the user account the corresponding properties MUST be set to null.
                type: object
                required:
                - user_id
                properties:
                  user_id:
                    type: string
                    description: 'A unique user identifier specific to the back-end, which could either be chosen by a user or is automatically generated by the back-end during the registration process at the back-end.

                      It is meant to be used as an identifier in URIs (e.g. for sharing purposes), which is primarily used in machine-to-machine communication. Preferrably use the human-readable property `name` to display the user''s name in user interfaces instead of the user identifier.'
                    pattern: ^[\w\-\.~]+$
                    example: john_doe
                  name:
                    type: string
                    description: The user name, a human-friendly displayable name. Could be  the user's real name or a nickname.
                  default_plan:
                    type: string
                    description: Name of the single plan the user is currently subscribed to if any.
                    example: free
                  storage:
                    title: User Storage
                    description: Information about the storage space available to the user.
                    type:
                    - object
                    - 'null'
                    required:
                    - free
                    - quota
                    properties:
                      free:
                        $ref: '#/components/schemas/storage_quota_free'
                      quota:
                        $ref: '#/components/schemas/max_storage_quota'
                  budget:
                    type:
                    - number
                    - 'null'
                    description: 'The remaining budget a user has available.

                      The value MUST be specified in the currency of the back-end.

                      The value SHOULD be set to `null` if no explicit limit applies.'
                  links:
                    description: "Links related to the user profile, e.g. where payments\nare handled or the user profile could be edited.\n\nProviding links with the following `rel` (relation) types is RECOMMENDED:\n\n1. `payment`: A page where users can recharge their user account with money or credits.\n\n2. `edit-form`: Points to a page where the user can edit his user profile.\n\n3. `alternate`: Any other representation of these (and potentially additional)\nuser information, e.g. the (public) user profile page.\nIt is RECOMMENDED to add descriptive titles for a better user experience.\n\n4. `related`: Any other user-specific links to be shown in clients,\ne.g. to user-specific settings, invoices, etc. It is RECOMMENDED to \nadd descriptive titles for a better user experience.\n\nFor additional relation types see also the lists of\n[common relation types in openEO](#section/API-Principles/Web-Linking)."
                    type: array
                    items:
                      $ref: '#/components/schemas/link'
                    example:
                    - href: https://openeo.example/john_doe/payment/
                      rel: payment
                    - href: https://openeo.example/john_doe/edit/
                      rel: edit-form
                    - href: https://openeo.example/john_doe/
                      rel: alternate
                      type: text/html
                      title: User profile
                    - href: https://openeo.example/john_doe.vcf
                      rel: alternate
                      type: text/vcard
                      title: vCard of John Doe
                    - href: https://openeo.example/john_doe/invoices
                      rel: related
                      type: text/html
                      title: Invoices
        4XX:
          $ref: '#/components/responses/client_error_auth'
        5XX:
          $ref: '#/components/responses/server_error'
components:
  schemas:
    link:
      title: Link
      description: A link to another resource on the web. Bases on [RFC 5899](https://www.rfc-editor.org/rfc/rfc5988.html).
      type: object
      required:
      - href
      - rel
      properties:
        rel:
          type: string
          description: Relationship between the current document and the linked document. SHOULD be a [registered link relation type](https://www.iana.org/assignments/link-relations/link-relations.xml) whenever feasible.
          example: related
        href:
          type: string
          description: The value MUST be a valid URL.
          format: uri
          example: https://openeo.example
        type:
          type: string
          description: The value MUST be a string that hints at the format used to represent data at the provided URI, preferably a media (MIME) type.
          example: text/html
        title:
          type: string
          description: Used as a human-readable label for a link.
          example: openEO
    log_links:
      description: 'Links related to this log entry / error, e.g. to a resource that

        provides further explanations.


        For relation types see the lists of

        [common relation types in openEO](#section/API-Principles/Web-Linking).'
      type: array
      items:
        $ref: '#/components/schemas/link'
      example:
      - href: https://openeo.example/docs/errors/SampleError
        rel: about
    storage_quota_free:
      type: integer
      description: Free storage space in bytes, which is still available to the user. Effectively, this is the disk quota minus the used space by the user, e.g. user-uploaded files and job results.
      example: 536870912
    max_storage_quota:
      type: integer
      description: Maximum storage space (disk quota) in bytes available to the user.
      example: 1073741824
    log_code:
      type: string
      description: The code is either one of the standardized error codes or a custom code, for example specified by a user in the `inspect` process.
      example: SampleError
    error:
      title: General Error
      description: 'An error object declares additional information about a client-side or server-side error.

        See also: * [Error Handling](#section/API-Principles/Error-Handling) in the API in general. * [Common Error Codes](errors.json)'
      type: object
      required:
      - code
      - message
      properties:
        id:
          type: string
          description: A back-end MAY add a unique identifier to the error response to be able to log and track errors with further non-disclosable details. A client could communicate this id to a back-end provider to get further information.
          example: 550e8400-e29b-11d4-a716-446655440000
        code:
          $ref: '#/components/schemas/log_code'
        message:
          type: string
          description: A message explaining what the client may need to change or what difficulties the server is facing.
          example: Parameter 'sample' is missing.
        links:
          $ref: '#/components/schemas/log_links'
  responses:
    server_error:
      description: 'The request can not be fulfilled due to an error at the back-end. The

        error is never the client’s fault and therefore it is reasonable for the

        client to retry the exact same request that triggered this response.


        The response body SHOULD contain a JSON error object. MUST be any HTTP

        status code specified in [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html#section-6.6).


        See also:

        * [Error Handling](#section/API-Principles/Error-Handling) in the API in general.

        * [Common Error Codes](errors.json)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    client_error_auth:
      description: 'The request can not be fulfilled due to an error on client-side, i.e. the

        request is invalid. The client SHOULD NOT repeat the request without

        modifications.


        The response body SHOULD contain a JSON error object.

        MUST be any HTTP status code specified in [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html#section-6.6).

        This request MUST respond with HTTP status codes 401 if authorization is required or

        403 if the authorization failed or access is forbidden in general to the

        authenticated user. HTTP status code 404 SHOULD be used if the value of

        a path parameter is invalid.


        See also:

        * [Error Handling](#section/API-Principles/Error-Handling) in the API in general.

        * [Common Error Codes](errors.json)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT or openEO
      description: "A Bearer token can be provided in two different formats:\n1. **JSON Web Token (JWT) - RECOMMENDED**\n\n   - Conformance class: `https://api.openeo.org/1.3.0/authentication/jwt`\n   \n   The Bearer token is an access token in [JWT](https://datatracker.ietf.org/doc/html/rfc7519) format\n   as defined in RFC 7519. For openEO, it MUST include the issuer in the\n   `iss` claim although being optional in RFC 7519.\n   If the concept of an issuer does not exist in an authentication method (e.g. in HTTP Basic),\n   implementations could use the endpoint for Basic Authentication as the issuer, for example.\n\n   openEO backend implementations MUST signal their support for JWT by listing the given\n   conformance class. Likewise, openEO clients SHOULD only use JWT when the openEO backend\n   lists the conformance class.\n\n2. **openEO Tokens - DEPRECATED**\n\n   - Conformance class: *None*\n\n   The Bearer Token is constructed from the authentication method, a\n   provider ID (if available) and the access token. All separated by a\n   forward slash `/`.\n\n   Examples (replace `TOKEN` with the actual access token):\n\n   - Basic authentication (no provider ID available): `basic//TOKEN`\n   - OpenID Connect (provider ID is `ms`): `oidc/ms/TOKEN`.\n     For OpenID Connect, the provider ID corresponds to the value\n     specified for `id` for each provider in `GET /credentials/oidc`.\n\n   All openEO backends MUST accept this method for backward compatibility\n   until version 2.0 of the specification.\n\n   The access tokens provided by the identity provider do not include\n   the prefix that includes the authentication method and provider ID.\n   The Bearer Token sent to the openEO backend MUST have the prefix, e.g. `basic//` for Basic authentication.\n   This means that the clients have to prepend the prefix.\n\nJWT and openEO tokens can be distinguished by the presence of a slash `/` in the token, which JWT can never contain due to the Base64 encoding."
    Basic:
      type: http
      scheme: basic
externalDocs:
  description: openEO Documentation
  url: https://openeo.org/documentation/1.0/