# Rotate an app's secret (shown once; the old one works 24 h more)

POST`/v1/oauth/clients/{client_id}/rotate-secret`[Token scope: `admin`](https://developers.tasksmate.indrasol.com/guides/authentication/#scopes)

Request

**curl**


```bash
curl -X POST "https://tasksmate-fdfsarhnf5gacfb7.eastus-01.azurewebsites.net/v1/oauth/clients/<client_id>/rotate-secret" \
  -H "Authorization: Bearer $TASKSMATE_TOKEN"
```

**Python**


```python
from tasksmate import TasksMate

tm = TasksMate()  # reads TASKSMATE_TOKEN
result = tm.oauth_clients.rotate_secret("<client_id>")
print(result)
```

Response 200

```json
{
  "allowed_scopes": [
    "tasks:write",
    "projects:read"
  ],
  "client_id": "tmc_Q2x9eLr0v2Zk5n8WcHt1YpUo",
  "client_secret": "tmcs_Ab3xQ9eLr0v2Zk5n8WcHt1YpUo4MiGs7Fj6Da-_Bq0R",
  "client_type": "confidential",
  "created_at": "2026-09-26T12:00:00Z",
  "created_by": "3f1c2a9e-0b7d-4c1e-9a55-2b8f0d6e4a10",
  "grants_count": 3,
  "homepage_url": "https://hr.example.com",
  "last_used_at": "2026-09-26T12:00:00Z",
  "name": "Acme HR",
  "org_id": "O0020",
  "redirect_uris": [
    "https://hr.example.com/oauth/callback"
  ],
  "registration": "developer",
  "review_state": "private",
  "status": "active",
  "updated_at": "2026-09-26T12:00:00Z",
  "use_count": 1204
}
```

A new secret, shown once in this response. The old one keeps working for 24 hours.

## Authorizations

-   **[bearerAuth](https://developers.tasksmate.indrasol.com/reference/#bearerauth)**
-   **[TasksMateToken](https://developers.tasksmate.indrasol.com/reference/#tasksmatetoken)**

## Parameters

### Path Parameters

**client\_id**

required

_Client Id_

string

## Responses

### 200

Successful Response

application/json

_OAuthClientCreated_

Returned by `oauth-clients.create` and `oauth-clients.rotate_secret`.

object

**client\_id**

required

_Client Id_

Public identifier (`tmc_…`)

string

**org\_id**

required

_Org Id_

string

**name**

required

_Name_

string

**logo\_url**

Any of:

**string**


string

**null**


null

**homepage\_url**

Any of:

**string**


string

**null**


null

**privacy\_url**

Any of:

**string**


string

**null**


null

**redirect\_uris**

required

_Redirect Uris_

Array<string>

**client\_type**

required

_Client Type_

string

Allowed values: confidential public

**allowed\_scopes**

required

_Allowed Scopes_

Array<string>

**registration**

_Registration_

string

default: developer

Allowed values: developer dynamic

**review\_state**

_Review State_

`private`: people outside your organization see an unreviewed-app warning when connecting

string

default: private

Allowed values: private listed

**status**

required

_Status_

string

Allowed values: active revoked

**grants\_count**

_Grants Count_

People connected to the app right now

integer

0

**use\_count**

_Use Count_

integer

0

**last\_used\_at**

Any of:

**string**


string format: date-time

**null**


null

**secret\_rotated\_at**

Any of:

**string**


string format: date-time

**null**


null

**previous\_secret\_expires\_at**

Any of:

**string**


string format: date-time

**null**


null

**created\_by**

Any of:

**string**


string

**null**


null

**created\_at**

Any of:

**string**


string format: date-time

**null**


null

**updated\_at**

Any of:

**string**


string format: date-time

**null**


null

**revoked\_at**

Any of:

**string**


string format: date-time

**null**


null

**revoked\_by**

Any of:

**string**


string

**null**


null

**client\_secret**

Any of:

**string**


string

**null**


null

Example

```json
{
  "allowed_scopes": [
    "tasks:write",
    "projects:read"
  ],
  "client_id": "tmc_Q2x9eLr0v2Zk5n8WcHt1YpUo",
  "client_secret": "tmcs_Ab3xQ9eLr0v2Zk5n8WcHt1YpUo4MiGs7Fj6Da-_Bq0R",
  "client_type": "confidential",
  "created_at": "2026-09-26T12:00:00Z",
  "created_by": "3f1c2a9e-0b7d-4c1e-9a55-2b8f0d6e4a10",
  "grants_count": 3,
  "homepage_url": "https://hr.example.com",
  "last_used_at": "2026-09-26T12:00:00Z",
  "name": "Acme HR",
  "org_id": "O0020",
  "redirect_uris": [
    "https://hr.example.com/oauth/callback"
  ],
  "registration": "developer",
  "review_state": "private",
  "status": "active",
  "updated_at": "2026-09-26T12:00:00Z",
  "use_count": 1204
}
```

### 400

Bad request — a query parameter outside what the operation accepts (`invalid-parameter`)

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Bad request",
  "status": 400,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 401

Missing or invalid bearer token

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Missing or invalid bearer token",
  "status": 401,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 403

Authenticated, but not allowed

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Authenticated, but not allowed",
  "status": 403,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 404

Not found

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Not found",
  "status": 404,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 409

Conflict (a duplicate, or an `Idempotency-Key` still in flight)

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Conflict (a duplicate, or an `Idempotency-Key` still in flight)",
  "status": 409,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 412

`If-Match` does not match the current `ETag`

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "`If-Match` does not match the current `ETag`",
  "status": 412,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 422

The body or query did not validate (`validation`), or an `Idempotency-Key` was reused

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "The body or query did not validate (`validation`), or an `Idempotency-Key` was reused",
  "status": 422,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 429

An access token over its per-minute limit (`rate-limit`; see `Retry-After`)

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "An access token over its per-minute limit (`rate-limit`; see `Retry-After`)",
  "status": 429,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 500

Unexpected server error — quote `request_id`

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Unexpected server error",
  "status": 500,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

---
Source: https://developers.tasksmate.indrasol.com/reference/operations/oauth-clientsrotate_secret/