# Authentication

The Movemint API uses **OAuth 2.0** for authentication and authorization. All API entity requests require a valid **Bearer token**.

#### Supported Grant Types

| Grant Type         | Use Case                                                         |
| ------------------ | ---------------------------------------------------------------- |
| Authorization Code | Server-side applications that can securely store a client secret |
| Client Credentials | Machine-to-machine communication with no user context            |

#### Step 1: Register an OAuth Application

Contact the Movemint team to register your OAuth application. You will receive a **Client ID** (`client_id`) and **Client Secret** (`client_secret`). You must also provide one or more **Redirect URIs** where users will be sent after authorizing your application.

#### Step 2: Authorization Code Flow

Redirect the user's browser to the authorization endpoint:

```
GET https://www.movemint.cc/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=
```

After the user approves access, they are redirected back to your `redirect_uri` with an authorization `code` query parameter:

```
https://your-app.com/callback?code=AUTHORIZATION_CODE
```

#### Step 3: Exchange the Code for Tokens

```bash
curl -X POST https://www.movemint.cc/oauth/token \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=YOUR_REDIRECT_URI
```

**Response:**

```json
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "REFRESH_TOKEN",
  "created_at": 1700000000
}
```

Access tokens expire after **2 hours** (7200 seconds) by default.

#### Step 4: Refresh an Expired Token

```bash
curl -X POST https://www.movemint.cc/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET
```

#### Step 5: Use the Token in API Requests

Include the access token as a Bearer token in the `Authorization` header:

```bash
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://www.movemint.cc/api/v1/me
```

#### Revoking Tokens

To revoke an access token or refresh token:

```bash
curl -X POST https://www.movemint.cc/oauth/revoke \
  -d token=TOKEN_TO_REVOKE \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET
```

## Obtain or refresh an access token

> Exchange an authorization code or refresh token for an access token.\
> This endpoint supports the \`authorization\_code\`, \`refresh\_token\`, and\
> \`client\_credentials\` grant types.<br>

````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Authentication","description":"The Movemint API uses **OAuth 2.0** for authentication and authorization. All API entity requests require a valid **Bearer token**.\n\n### Supported Grant Types\n\n| Grant Type | Use Case |\n|------------|----------|\n| Authorization Code | Server-side applications that can securely store a client secret |\n| Client Credentials | Machine-to-machine communication with no user context |\n\n### Step 1: Register an OAuth Application\n\nContact the Movemint team to register your OAuth application. You will\nreceive a **Client ID** (`client_id`) and **Client Secret**\n(`client_secret`). You must also provide one or more **Redirect URIs**\nwhere users will be sent after authorizing your application.\n\n### Step 2: Authorization Code Flow\n\nRedirect the user's browser to the authorization endpoint:\n\n```\nGET https://www.movemint.cc/oauth/authorize\n  ?client_id=YOUR_CLIENT_ID\n  &redirect_uri=YOUR_REDIRECT_URI\n  &response_type=code\n  &scope=\n```\n\nAfter the user approves access, they are redirected back to your\n`redirect_uri` with an authorization `code` query parameter:\n\n```\nhttps://your-app.com/callback?code=AUTHORIZATION_CODE\n```\n\n### Step 3: Exchange the Code for Tokens\n\n```bash\ncurl -X POST https://www.movemint.cc/oauth/token \\\n  -d grant_type=authorization_code \\\n  -d code=AUTHORIZATION_CODE \\\n  -d client_id=YOUR_CLIENT_ID \\\n  -d client_secret=YOUR_CLIENT_SECRET \\\n  -d redirect_uri=YOUR_REDIRECT_URI\n```\n\n**Response:**\n\n```json\n{\n  \"access_token\": \"ACCESS_TOKEN\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 7200,\n  \"refresh_token\": \"REFRESH_TOKEN\",\n  \"created_at\": 1700000000\n}\n```\n\nAccess tokens expire after **2 hours** (7200 seconds) by default.\n\n### Step 4: Refresh an Expired Token\n\n```bash\ncurl -X POST https://www.movemint.cc/oauth/token \\\n  -d grant_type=refresh_token \\\n  -d refresh_token=REFRESH_TOKEN \\\n  -d client_id=YOUR_CLIENT_ID \\\n  -d client_secret=YOUR_CLIENT_SECRET\n```\n\n### Step 5: Use the Token in API Requests\n\nInclude the access token as a Bearer token in the `Authorization` header:\n\n```bash\ncurl -H \"Authorization: Bearer ACCESS_TOKEN\" \\\n  https://www.movemint.cc/api/v1/me\n```\n\n### Revoking Tokens\n\nTo revoke an access token or refresh token:\n\n```bash\ncurl -X POST https://www.movemint.cc/oauth/revoke \\\n  -d token=TOKEN_TO_REVOKE \\\n  -d client_id=YOUR_CLIENT_ID \\\n  -d client_secret=YOUR_CLIENT_SECRET\n```\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[],"paths":{"/oauth/token":{"post":{"tags":["Authentication"],"summary":"Obtain or refresh an access token","description":"Exchange an authorization code or refresh token for an access token.\nThis endpoint supports the `authorization_code`, `refresh_token`, and\n`client_credentials` grant types.\n","operationId":"createToken","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthorizationCodeGrantRequest"},{"$ref":"#/components/schemas/RefreshTokenGrantRequest"},{"$ref":"#/components/schemas/ClientCredentialsGrantRequest"}]}}}},"responses":{"200":{"description":"Token issued successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"Invalid grant or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"401":{"description":"Invalid client credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}}},"components":{"schemas":{"AuthorizationCodeGrantRequest":{"type":"object","required":["grant_type","code","client_id","client_secret","redirect_uri"],"properties":{"grant_type":{"type":"string","enum":["authorization_code"]},"code":{"type":"string","description":"The authorization code received from the authorization endpoint"},"client_id":{"type":"string","description":"Your application's Client ID"},"client_secret":{"type":"string","description":"Your application's Client Secret"},"redirect_uri":{"type":"string","format":"uri","description":"The same redirect URI used in the authorization request"}}},"RefreshTokenGrantRequest":{"type":"object","required":["grant_type","refresh_token","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["refresh_token"]},"refresh_token":{"type":"string","description":"The refresh token issued alongside the access token"},"client_id":{"type":"string","description":"Your application's Client ID"},"client_secret":{"type":"string","description":"Your application's Client Secret"}}},"ClientCredentialsGrantRequest":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string","description":"Your application's Client ID"},"client_secret":{"type":"string","description":"Your application's Client Secret"}}},"TokenResponse":{"type":"object","required":["access_token","token_type","expires_in","created_at"],"properties":{"access_token":{"type":"string","description":"The access token to use in API requests"},"token_type":{"type":"string","enum":["Bearer"],"description":"Always \"Bearer\""},"expires_in":{"type":"integer","description":"Token lifetime in seconds (default 7200 = 2 hours)"},"refresh_token":{"type":"string","description":"Token used to obtain a new access token when the current one expires. Not present for client_credentials grants."},"created_at":{"type":"integer","description":"Unix timestamp of when the token was created"}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}}}}}
````

## Revoke a token

> Revoke an access token or refresh token. After revocation, the token\
> can no longer be used to access protected resources.<br>

````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Authentication","description":"The Movemint API uses **OAuth 2.0** for authentication and authorization. All API entity requests require a valid **Bearer token**.\n\n### Supported Grant Types\n\n| Grant Type | Use Case |\n|------------|----------|\n| Authorization Code | Server-side applications that can securely store a client secret |\n| Client Credentials | Machine-to-machine communication with no user context |\n\n### Step 1: Register an OAuth Application\n\nContact the Movemint team to register your OAuth application. You will\nreceive a **Client ID** (`client_id`) and **Client Secret**\n(`client_secret`). You must also provide one or more **Redirect URIs**\nwhere users will be sent after authorizing your application.\n\n### Step 2: Authorization Code Flow\n\nRedirect the user's browser to the authorization endpoint:\n\n```\nGET https://www.movemint.cc/oauth/authorize\n  ?client_id=YOUR_CLIENT_ID\n  &redirect_uri=YOUR_REDIRECT_URI\n  &response_type=code\n  &scope=\n```\n\nAfter the user approves access, they are redirected back to your\n`redirect_uri` with an authorization `code` query parameter:\n\n```\nhttps://your-app.com/callback?code=AUTHORIZATION_CODE\n```\n\n### Step 3: Exchange the Code for Tokens\n\n```bash\ncurl -X POST https://www.movemint.cc/oauth/token \\\n  -d grant_type=authorization_code \\\n  -d code=AUTHORIZATION_CODE \\\n  -d client_id=YOUR_CLIENT_ID \\\n  -d client_secret=YOUR_CLIENT_SECRET \\\n  -d redirect_uri=YOUR_REDIRECT_URI\n```\n\n**Response:**\n\n```json\n{\n  \"access_token\": \"ACCESS_TOKEN\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 7200,\n  \"refresh_token\": \"REFRESH_TOKEN\",\n  \"created_at\": 1700000000\n}\n```\n\nAccess tokens expire after **2 hours** (7200 seconds) by default.\n\n### Step 4: Refresh an Expired Token\n\n```bash\ncurl -X POST https://www.movemint.cc/oauth/token \\\n  -d grant_type=refresh_token \\\n  -d refresh_token=REFRESH_TOKEN \\\n  -d client_id=YOUR_CLIENT_ID \\\n  -d client_secret=YOUR_CLIENT_SECRET\n```\n\n### Step 5: Use the Token in API Requests\n\nInclude the access token as a Bearer token in the `Authorization` header:\n\n```bash\ncurl -H \"Authorization: Bearer ACCESS_TOKEN\" \\\n  https://www.movemint.cc/api/v1/me\n```\n\n### Revoking Tokens\n\nTo revoke an access token or refresh token:\n\n```bash\ncurl -X POST https://www.movemint.cc/oauth/revoke \\\n  -d token=TOKEN_TO_REVOKE \\\n  -d client_id=YOUR_CLIENT_ID \\\n  -d client_secret=YOUR_CLIENT_SECRET\n```\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[],"paths":{"/oauth/revoke":{"post":{"tags":["Authentication"],"summary":"Revoke a token","description":"Revoke an access token or refresh token. After revocation, the token\ncan no longer be used to access protected resources.\n","operationId":"revokeToken","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["token","client_id","client_secret"],"properties":{"token":{"type":"string","description":"The access token or refresh token to revoke"},"client_id":{"type":"string","description":"Your application's Client ID"},"client_secret":{"type":"string","description":"Your application's Client Secret"}}}}}},"responses":{"200":{"description":"Token revoked successfully (always returns 200, even if the token was already revoked)"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}}},"components":{"schemas":{"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}}}}}
````

## Get token info

> Retrieve metadata about the current access token, including its\
> scopes, expiration, and associated resource owner and application.<br>

````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Authentication","description":"The Movemint API uses **OAuth 2.0** for authentication and authorization. All API entity requests require a valid **Bearer token**.\n\n### Supported Grant Types\n\n| Grant Type | Use Case |\n|------------|----------|\n| Authorization Code | Server-side applications that can securely store a client secret |\n| Client Credentials | Machine-to-machine communication with no user context |\n\n### Step 1: Register an OAuth Application\n\nContact the Movemint team to register your OAuth application. You will\nreceive a **Client ID** (`client_id`) and **Client Secret**\n(`client_secret`). You must also provide one or more **Redirect URIs**\nwhere users will be sent after authorizing your application.\n\n### Step 2: Authorization Code Flow\n\nRedirect the user's browser to the authorization endpoint:\n\n```\nGET https://www.movemint.cc/oauth/authorize\n  ?client_id=YOUR_CLIENT_ID\n  &redirect_uri=YOUR_REDIRECT_URI\n  &response_type=code\n  &scope=\n```\n\nAfter the user approves access, they are redirected back to your\n`redirect_uri` with an authorization `code` query parameter:\n\n```\nhttps://your-app.com/callback?code=AUTHORIZATION_CODE\n```\n\n### Step 3: Exchange the Code for Tokens\n\n```bash\ncurl -X POST https://www.movemint.cc/oauth/token \\\n  -d grant_type=authorization_code \\\n  -d code=AUTHORIZATION_CODE \\\n  -d client_id=YOUR_CLIENT_ID \\\n  -d client_secret=YOUR_CLIENT_SECRET \\\n  -d redirect_uri=YOUR_REDIRECT_URI\n```\n\n**Response:**\n\n```json\n{\n  \"access_token\": \"ACCESS_TOKEN\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 7200,\n  \"refresh_token\": \"REFRESH_TOKEN\",\n  \"created_at\": 1700000000\n}\n```\n\nAccess tokens expire after **2 hours** (7200 seconds) by default.\n\n### Step 4: Refresh an Expired Token\n\n```bash\ncurl -X POST https://www.movemint.cc/oauth/token \\\n  -d grant_type=refresh_token \\\n  -d refresh_token=REFRESH_TOKEN \\\n  -d client_id=YOUR_CLIENT_ID \\\n  -d client_secret=YOUR_CLIENT_SECRET\n```\n\n### Step 5: Use the Token in API Requests\n\nInclude the access token as a Bearer token in the `Authorization` header:\n\n```bash\ncurl -H \"Authorization: Bearer ACCESS_TOKEN\" \\\n  https://www.movemint.cc/api/v1/me\n```\n\n### Revoking Tokens\n\nTo revoke an access token or refresh token:\n\n```bash\ncurl -X POST https://www.movemint.cc/oauth/revoke \\\n  -d token=TOKEN_TO_REVOKE \\\n  -d client_id=YOUR_CLIENT_ID \\\n  -d client_secret=YOUR_CLIENT_SECRET\n```\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"schemas":{"TokenInfo":{"type":"object","required":["scopes","expires_in_seconds","application","created_at"],"properties":{"resource_owner_id":{"type":"integer","format":"int64","description":"The ID of the athlete who authorized the token"},"scopes":{"type":"array","items":{"type":"string"},"description":"List of scopes granted to this token"},"expires_in_seconds":{"type":"integer","description":"Seconds until the token expires"},"application":{"type":"object","properties":{"uid":{"type":"string","description":"The OAuth application's Client ID"}}},"created_at":{"type":"integer","description":"Unix timestamp of when the token was created"}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}}}},"paths":{"/oauth/token/info":{"get":{"tags":["Authentication"],"summary":"Get token info","description":"Retrieve metadata about the current access token, including its\nscopes, expiration, and associated resource owner and application.\n","operationId":"getTokenInfo","responses":{"200":{"description":"Token information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenInfo"}}}},"401":{"description":"Token is invalid or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}}}}
````


---

# 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://movemint.gitbook.io/movemint-developer-docs/open-api-specification/authentication.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.