From 69cea336c7f3cdf280d25adde2b08d5589bb214e Mon Sep 17 00:00:00 2001 From: Daniel Subiabre Date: Tue, 24 Feb 2026 17:34:22 +0100 Subject: [PATCH] feat: update auth section in api description --- src/OpenApi/OpenApiDescription.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/src/OpenApi/OpenApiDescription.md b/src/OpenApi/OpenApiDescription.md index 2417bbe..cbbcad7 100644 --- a/src/OpenApi/OpenApiDescription.md +++ b/src/OpenApi/OpenApiDescription.md @@ -7,25 +7,20 @@ v4 exposes a REST API with predictable and resource-oriented URLs, accepts reque This API is documented in the OpenApi initiative [Specification v3.1.0](https://spec.openapis.org/oas/v3.1.0), which allows v4 to be easily understood by API development suites, documentation generators and SDK generators for the convenience of developers and API users. Most of the spec is generated automatically as changes are introduced, but some additional content such as this introduction and other sections might not be updated as regularly. -This API is still in early development and is not set to have backward compatibility with the Goteo API v1 (http://api.goteo.org/v1/). Major changes are to be expected. +This API is still in early development and is not set to have backward compatibility with the Goteo API v1 (https://api.goteo.org/v1/). Major changes are to be expected. # Authentication -The v4 API uses Access Tokens to authenticate requests. To use a Token, include it in the `Authorization` header using the [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) strategy. +The v4 API uses [OAuth 2.0](https://oauth.net/2/) to authenticate requests from consumer applications. -```sh -curl -X 'GET' \ - 'https://api.goteo.org/v4/projects?page=1' \ - -H 'accept: application/json' \ - -H 'Authorization: Bearer ' -``` +Auth clients are issued on a case-by-case basis. You may reach out to us in order to obtain client credentials to initiate auth flows. -UserTokens exist under an User's scope, when you obtain a token this will only grant you as much permissions as the User under which it was created. +The following paths are available for authentication: +- **`POST /oauth/token`** to obtain Access Tokens +- **`GET /oauth/authorize`** to initiate *Authorization Code Grant* flows -To obtain a UserToken you must send a POST request to [/v4/user_tokens](/v4/user_tokens) with the User login credentials (identifier and password) in the payload. If the credentials are correct a UserToken will be created, the `token` property value of which you must include in future requests. - -Users can delete UserTokens owned by them at any moment, revoking your application's access to the v4 API on their behalf. When a UserToken fails to authenticate a request you will receive a 401 Unauthorized response from the API, at which point your application must look to get a new UserToken from the User. +Please notice these paths do not have the `/v4` path prefix. # Localization