openapi: 3.2.0 info: title: Openeo Account Management API version: 1.3.0 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 description: 'Operations tagged Account Management across 2 of this provider''s published API definitions: openeo-api-openapi.yaml, openeo-openapi.yml. Each path carries the servers of the definition it was published in.' 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' 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.' /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' 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.' /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' 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.' components: schemas: 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 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 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 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 max_storage_quota: type: integer description: Maximum storage space (disk quota) in bytes available to the user. example: 1073741824 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: 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' 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' 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/ x-refined-from: - openeo-api-openapi.yaml - openeo-openapi.yml