On premise authentication

ManicTime Server API

You can use ManicTime Server API in order to programmatically access timeline data using Timeline API.

How a script or an application signs in depends on the sign-in system of your server:

  • New sign-in system (ManicTime Server v2026.3) - use an API token or an API client. See New sign-in system.
  • Old sign-in system - use Windows authentication or a ManicTime username and password. See Old sign-in system.

To see which system your server uses, go to Administration -> User management -> Sign-in methods. If the page shows New sign-in system available, the server uses the old sign-in system. See Sign-in methods.

New sign-in system

On a server with the new sign-in system, the old ways to sign in do not work. The server refuses a username and password at /api/token, and it does not accept Windows authentication for API requests.

Use one of these:

  • API token - for a script that uses the API as one user. See API token.
  • API client - for an application that users sign in to through the browser. See API client.

Administrators create both on the Developer page.

API token

  1. Create an API token on the Developer page.
  2. Send the token in the Authorization header of each API call.
GET https://manictime.example.com/api
Authorization: Bearer mt_api_<token>
Accept: application/vnd.manictime.v3+json

The script has the roles and rights of the user that the token belongs to. If the token is deleted or expired, or the user is archived, the server answers 401 Unauthorized.

API client

An API client uses the OAuth 2.0 authorization code flow with PKCE. The user signs in on the ManicTime Server sign-in page with any enabled sign-in method. The application then calls the API as that user.

  1. Register the application as an API client on the Developer page. You get a client ID. A Web application also gets a client secret.

  2. Get the endpoint URLs from the OpenID Connect configuration of your server:

    GET https://manictime.example.com/.well-known/openid-configuration
    Accept: application/json
    

    Use authorization_endpoint, token_endpoint and revocation_endpoint from the response.

  3. Open authorization_endpoint in the browser:

    GET <authorization_endpoint>
      ?response_type=code
      &client_id=<client_id>
      &redirect_uri=<redirect_uri>
      &scope=openid+profile+api+offline_access
      &state=<state>
      &code_challenge=<code_challenge>
      &code_challenge_method=S256
    

    The redirect_uri must be one of the redirect URIs of the API client. The server accepts only S256 as code_challenge_method.

  4. The user signs in. The browser then calls redirect_uri with the authorization code in the code parameter.

  5. Exchange the code for tokens:

    POST <token_endpoint>
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>&code_verifier=<code_verifier>&client_id=<client_id>&client_secret=<client_secret>
    

    A Native application has no client secret, so leave out client_secret. A Web application can also send the client ID and the client secret with HTTP Basic authentication.

  6. Call the API with the access token:

    GET https://manictime.example.com/api
    Authorization: Bearer <access_token>
    Accept: application/vnd.manictime.v3+json
    
  7. When the access token expires, get new tokens with the refresh token:

    POST <token_endpoint>
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>&client_secret=<client_secret>
    

An access token is valid for 10 minutes. Each refresh gives a new refresh token. Use the new refresh token for the next refresh, and do not refresh with the same token two times at the same time.

For an MCP client, also request the mcp:tools scope.

Old sign-in system

The sections below are for servers with the old sign-in system.

Authentication - Windows users

When server is configured with Windows users, Kerberos or NTLM is used for authentication. Please use a client HTTP library that supports these protocols.

Authentication - ManicTime users

When server is configured with ManicTime users, OAuth 2.0 is used for authentication. Oauth 2.0 Resource Owner Password Flow is used, where after sending username and password your app gets access token. You use access token in order to make authorized API calls.

You need to follow these steps in order to get and use access token:

1. Get token endpoint URL
2. Get access token
3. Call API

1. Get token endpoint URL

To get token endpoint URL, make HTTP call without authorization headers

GET http://localhost:8080/api
Accept: application/vnd.manictime.v3+json 
HTTP/1.1 401 Unauthorized
Content-Type: application/vnd.manictime.v3+json charset=utf-8
WWW-Authenticate: Bearer

{ 
    "links": [   
        {      
            "rel": "manictime/token",
            "href": "http://localhost:8080/api/token"    
        }  
    ]
}

2. Get access token

To get access token, call token endpoint URL with username and password

POST http://localhost:8080/api/token
Content-Type: application/x-www-form-urlencoded
Accept: application/vnd.manictime.v3+json

grant_type=password&username=<username>&password=<password>
HTTP/1.1 200 OK
Content-Type: application/json

{  
    "token": <access_token>
}

3. Call API

You can need to include access token with each API call.

GET http://localhost:8080/api
Authorization: Bearer <access_token>
Accept: application/vnd.manictime.v3+json
HTTP/1.1 200 OK
Content-Type: application/vnd.manictime.v3+json; charset=utf-8

{
    "links": [
        {
            "rel": "self",
            "href": "http://localhost:8080/api/"
        },
        {
            "rel": "manictime/timelines",
            "href": "http://localhost:8080/api/timelines"
        },
        {
            "rel": "manictime/environments",
            "href": "http://localhost:8080/api/environments"
        },
        {
            "rel": "manictime/screenshots",
            "href": "http://localhost:8080/api/screenshots"
        },
        {
            "rel": "manictime/clientState",
            "href": "http://localhost:8080/api/clientState"
        },
        {
            "rel": "manictime/tagcombinationlist",
            "href": "http://localhost:8080/api/tagcombinationlist"
        },
        {
            "rel": "manictime/clientsettings",
            "href": "http://localhost:8080/api/clientSettings"
        }
    ]
}