Skip to content

api-changes-8.7.0 #240

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Roxie-32 wants to merge 1 commit into from
Closed

api-changes-8.7.0 #240

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 74 additions & 4 deletions authentication.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -742,6 +742,76 @@ paths:
status: success
data:
message: You've been logged out!
/api/v1/loginCode.redeem:
post:
tags:
- Authentication
summary: Redeem Login Code
description: |-
Redeems a one-time login code for a login token. When the modern server-side OAuth flow is enabled through the `Accounts_OAuth_Use_Modern_Flow` setting, the server completes the OAuth login and redirects the browser back to the workspace with a `loginCode` query parameter. Call this endpoint with that code to get the `loginToken` and `userId` for the session. Pass the `loginToken` as the `X-Auth-Token` header and the `userId` as the `X-User-Id` header in later requests.

The endpoint does not require an authenticated session. It is rate-limited to 10 requests per minute per caller. Each code is a 64-character string, is single-use, and expires 60 seconds after it is issued.

### Changelog
| Version | Description |
| ------- | ----------- |
| 8.7.0 | Added |
operationId: post-api-v1-loginCode.redeem
requestBody:
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: The one-time login code issued by the server-side OAuth flow. It must be exactly 64 characters long.
example: 4f1d2c3b4a5968778695a4b3c2d1e0f1123456789abcdef00fedcba987654321
required:
- code
examples:
Example 1:
value:
code: 4f1d2c3b4a5968778695a4b3c2d1e0f1123456789abcdef00fedcba987654321
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
loginToken:
type: string
userId:
type: string
success:
type: boolean
examples:
Redemption successful:
value:
loginToken: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq
userId: aobEdbYhXfu5hkeqG
success: true
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
# <!-- TODO: Verify the exact error body returned when the `code` body parameter fails schema validation (missing, wrong length, or extra properties) on POST /api/v1/loginCode.redeem. -->
examples:
Invalid or expired code:
value:
success: false
error: error-invalid-code
'401':
$ref: '#/components/responses/authorizationError'
/api/v1/me:
get:
tags:
Expand Down Expand Up @@ -1121,14 +1191,14 @@ paths:
- Two-Factor Authentication
summary: Send Two-Factor Challenge Email Code
description: |-
Sends a two-factor authentication code by email for an in-progress login challenge. Use this endpoint after a login attempt returns a `challengeId` for the email two-factor method, to deliver a fresh code to the user.
Sends a two-factor authentication code by email for an in-progress login challenge. When a user signs in through the server-side OAuth flow and their account requires email two-factor authentication, the server issues a `challengeId` and sends an initial code automatically. Use this endpoint with that `challengeId` to deliver a fresh code to the user.

The endpoint does not require an authenticated session. It is rate-limited to 5 requests per minute per caller. The challenge must exist, must not be expired, and must use the `email` method.

### Changelog
| Version | Description |
| ------- | ----------- |
| 8.5.0 | Added |
| 8.7.0 | Added |
operationId: post-api-v1-twoFactorChallenges.sendEmailCode
requestBody:
content:
Expand Down Expand Up @@ -1194,14 +1264,14 @@ paths:
- Two-Factor Authentication
summary: Verify Two-Factor Challenge
description: |-
Verifies a two-factor authentication code submitted against a pending challenge and, on success, returns a login token for the associated user. Use this endpoint to complete the second factor of a login flow that issued a `challengeId`.
Verifies a two-factor authentication code submitted against a pending challenge and, on success, returns a login token for the associated user. Use this endpoint to complete the second factor of a server-side OAuth login that issued a `challengeId`. It supports the `email` and `totp` challenge methods.

The endpoint does not require an authenticated session. It is rate-limited to 5 requests per minute per caller. Exceeding the per-user maximum failed attempts removes the challenge and returns a `totp-max-attempts` error.

### Changelog
| Version | Description |
| ------- | ----------- |
| 8.5.0 | Added |
| 8.7.0 | Added |
operationId: post-api-v1-twoFactorChallenges.verifyChallenge
requestBody:
content:
Expand Down
168 changes: 168 additions & 0 deletions integrations.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,174 @@ paths:
success: false
error: 'must have required property ''id'' [invalid-params]'
errorType: invalid-params
/api/v1/integrations.clearHistory:
post:
tags:
- Integration
summary: Clear Integration History
description: |-
Clear the history of an outgoing <a href='https://docs.rocket.chat/docs/integrations' target='_blank'>integration</a>. This endpoint replaces the deprecated `clearIntegrationHistory` DDP method, which is scheduled for removal in version 9.0.0.

Any of the following permissions is required:
* `manage-outgoing-integrations`
* `manage-own-outgoing-integrations` (clears history only for integrations created by the calling user)

### Changelog
|Version | Description |
| ---------------- | ------------|
|8.7.0 | Added |
operationId: post-api-v1-integrations.clearHistory
parameters:
- $ref: '#/components/parameters/X-Auth-Token'
- $ref: '#/components/parameters/X-User-Id'
requestBody:
content:
application/json:
schema:
type: object
properties:
integrationId:
type: string
description: The ID of the integration whose history you want to clear.
example: nvdQuJQ6tE9HRFBzd
required:
- integrationId
examples:
Example 1:
value:
integrationId: nvdQuJQ6tE9HRFBzd
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
examples:
Success Example:
value:
success: true
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
errorType:
type: string
examples:
Example 1:
value:
success: false
error: 'must have required property ''integrationId'' [invalid-params]'
errorType: invalid-params
Example 2:
value:
success: false
error: 'Invalid integration [error-invalid-integration]'
errorType: error-invalid-integration
Example 3:
value:
success: false
error: 'Unauthorized [not_authorized]'
errorType: not_authorized
'401':
$ref: '#/components/responses/authorizationError'
/api/v1/integrations.replayOutgoing:
post:
tags:
- Integration
summary: Replay Outgoing Integration
description: |-
Replay a history entry of an outgoing <a href='https://docs.rocket.chat/docs/integrations' target='_blank'>integration</a>, triggering the integration again with the recorded data. This endpoint replaces the deprecated `replayOutgoingIntegration` DDP method, which is scheduled for removal in version 9.0.0.

Any of the following permissions is required:
* `manage-outgoing-integrations`
* `manage-own-outgoing-integrations` (replays only integrations created by the calling user)

### Changelog
|Version | Description |
| ---------------- | ------------|
|8.7.0 | Added |
operationId: post-api-v1-integrations.replayOutgoing
parameters:
- $ref: '#/components/parameters/X-Auth-Token'
- $ref: '#/components/parameters/X-User-Id'
requestBody:
content:
application/json:
schema:
type: object
properties:
integrationId:
type: string
description: The ID of the outgoing integration.
example: nvdQuJQ6tE9HRFBzd
historyId:
type: string
description: The ID of the integration history entry to replay. Use the <a href='https://developer.rocket.chat/apidocs/get-integration-history' target='_blank'>Get Integration History</a> endpoint to list history entries.
example: 8G2GfBz3prSampleId
required:
- integrationId
- historyId
examples:
Example 1:
value:
integrationId: nvdQuJQ6tE9HRFBzd
historyId: 8G2GfBz3prSampleId
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
examples:
Success Example:
value:
success: true
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
errorType:
type: string
examples:
Example 1:
value:
success: false
error: 'must have required property ''historyId'' [invalid-params]'
errorType: invalid-params
Example 2:
value:
success: false
error: 'Invalid integration [error-invalid-integration]'
errorType: error-invalid-integration
Example 3:
value:
success: false
error: 'Invalid Integration History [error-invalid-integration-history]'
errorType: error-invalid-integration-history
'401':
$ref: '#/components/responses/authorizationError'
/api/v1/integrations.list:
get:
tags:
Expand Down
82 changes: 82 additions & 0 deletions miscellaneous.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1259,6 +1259,88 @@ paths:
'403':
$ref: '#/components/responses/forbiddenError'

# TODO: Confirm the developer.rocket.chat slug for the "Add License" endpoint referenced in the description below.
/api/v1/licenses.validate:
post:
tags:
- Licenses
summary: Validate License
description: |-
<div style="text-align: center; margin: 1rem 0 1rem 0;"><img src="https://raw.githubusercontent.com/RocketChat/Rocket.Chat-Open-API/main/images/premium.svg" alt="Premium tag" style="display: block; margin: auto;"></div>

Validates a Rocket.Chat license against the current workspace without applying it. Use this endpoint to preview a license before applying it with the <b>Add License</b> endpoint. It accepts both V2 and V3 (JWT) license formats.

A valid license returns a success response. An invalid or implausible license returns a failure response with the validation behaviors that rejected it listed in the `reasons` array.

Permission required: `edit-privileged-setting`.
### Changelog
| Version | Description |
| ---------------- | ------------|
|8.7.0 | Added |
operationId: post-api-v1-licenses.validate
parameters:
- $ref: '#/components/parameters/Auth-Token'
- $ref: '#/components/parameters/UserId'
requestBody:
content:
application/json:
schema:
type: object
properties:
license:
type: string
description: The encrypted license string to validate.
required:
- license
examples:
Example:
value:
license: VFJ0vHf3Jm9AR0minB342MLaHRlZdc3Du5nf0E5Sv0QJ4SUkEIaU2boCYaDsxQ2N1UL4uhLjCF9M7iCZ/yxafJjxbHvOu1D5rOfdgO4RKlAGE9tGHDidJR9crJyXVb16jPHHvLSkUFzb7HoIq/nUXxU8gEgT3uJ9u2+Dw5ukDLX3SG2AFq1hLoPSZqsP6g2AQo=
# TODO: Verify the exact 400 body shape and status code returned by API.v1.failure for an invalid license (error string 'license-invalid' and reasons[] items).
responses:
'200':
$ref: '#/components/responses/trueSuccess'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
reasons:
type: array
items:
type: object
properties:
behavior:
type: string
reason:
type: string
modules:
type: array
items:
type: string
limit:
type: string
examples:
Invalid License:
value:
success: false
error: license-invalid
reasons:
- behavior: prevent_installation
reason: url
- behavior: invalidate_license
reason: period
'401':
$ref: '#/components/responses/authorizationError'
'403':
$ref: '#/components/responses/forbiddenError'

/licenses.maxActiveUsers:
get:
tags:
Expand Down
Loading