# oauth2

## GET /api/v0/users/me/oauth2/authorizations

> Lists the OAuth2 authorizations (grants) of the currently authenticated user.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.2"},"tags":[{"name":"hq_oauth2"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_OAuth2UserAuthorizationList":{"type":"object","description":"Contains a list of OAuth2 user authorizations.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/hq_OAuth2UserAuthorization"}}},"required":["items"]},"hq_OAuth2UserAuthorization":{"type":"object","properties":{"grant_id":{"type":"string"},"grant_issued_at":{"type":"string","format":"date-time"},"app_name":{"type":"string"},"app_display_name":{"type":"string"},"app_client_id":{"type":"string"},"app_provenance":{"$ref":"#/components/schemas/hq_OAuth2AppProvenance"},"scope":{"type":"array","items":{"type":"string"}}},"required":["grant_id","grant_issued_at","app_name","app_display_name","app_client_id","app_provenance","scope"]},"hq_OAuth2AppProvenance":{"type":"string","description":"Tells how the OAuth2 Application was registered.","enum":["dcr","api"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v0/users/me/oauth2/authorizations":{"get":{"description":"Lists the OAuth2 authorizations (grants) of the currently authenticated user.","operationId":"listCurrentUserOAuth2Authorizations","responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_OAuth2UserAuthorizationList"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_oauth2"]}}}}
```

## DELETE /api/v0/users/me/oauth2/authorizations/{id}

> Revokes the specified OAuth2 authorization (grant) of the currently authenticated user.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.2"},"tags":[{"name":"hq_oauth2"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v0/users/me/oauth2/authorizations/{id}":{"delete":{"description":"Revokes the specified OAuth2 authorization (grant) of the currently authenticated user.","operationId":"revokeCurrentUserOAuth2Authorization","parameters":[{"in":"path","name":"id","description":"Identifier of the OAuth2 authorization grant to revoke.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Happy response. The authorization was revoked or did not exist."},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_oauth2"]}}}}
```

## POST /api/v1/oauth2/authorize

> Authorises the client to act on behalf of the principal that makes the request.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.2"},"tags":[{"name":"hq_oauth2"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_OAuth2AuthorizationRequest":{"type":"object","properties":{"client_id":{"type":"string"},"redirect_uri":{"type":"string"},"response_type":{"type":"string"},"scope":{"type":"array","items":{"type":"string"}},"state":{"type":"string"},"code_challenge":{"type":"string"},"code_challenge_method":{"type":"string"}},"required":["client_id","redirect_uri","response_type","scope","state"]},"hq_OAuth2AuthorizationResponse":{"type":"object","properties":{"redirect_uri":{"type":"string"}},"required":["redirect_uri"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/oauth2/authorize":{"post":{"description":"Authorises the client to act on behalf of the principal that makes the request.","operationId":"authorizeOAuth2Client","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_OAuth2AuthorizationRequest"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_OAuth2AuthorizationResponse"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_oauth2"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lenses.io/latest/api-reference/reference/oauth2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.