{"openapi":"3.0.0","info":{"title":"Authentication","description":"The official SeaTable API Reference (OpenAPI 3.0).","version":"6.2"},"servers":[{"url":"https://{server}","variables":{"server":{"default":"cloud.seatable.io"}}}],"x-readme":{"explorer-enabled":true,"metrics-enabled":false,"proxy-enabled":false},"tags":[{"name":"Account-Token","description":"Endpoints related to account tokens"},{"name":"API-Token","description":"Endpoints related to API tokens"},{"name":"Base-Token","description":"Endpoints related to base tokens"}],"components":{"securitySchemes":{"AccountTokenAuth":{"type":"http","scheme":"bearer","description":"This is the [Account-Token](/reference/authentication).","bearerFormat":"Account-Token"},"ApiTokenAuth":{"type":"http","scheme":"bearer","description":"This is the [API-Token](/reference/authentication).","bearerFormat":"API-Token"}},"parameters":{"X-SEAFILE-OTP":{"name":"X-SEAFILE-OTP","in":"header","schema":{"type":"string","pattern":"^\\d{6}$"},"description":"Two-factor token (usually generated with a mobile app like the google authenticator), optional, only needed if 2FA is activated for your account.\n"},"expiration_time":{"name":"exp","description":"Expiration time of the generated access token.\nExamples: 5h (= 5 hours) or 3d (= 3 days)\n","in":"query","schema":{"type":"string","default":"3d"}},"workspace_id":{"name":"workspace_id","description":"The id of the workspace. For an explanation how to get the *workspace_id*, check out this [help-article](https://seatable.com/help/find-workspace-id-group/). \nAlternatively the API endpoint [get metadata](/reference/getmetadata) can be used.\n","in":"path","schema":{"type":"integer","minimum":1},"required":true,"example":127},"base_name":{"name":"base_name","description":"The name of your base.","in":"path","schema":{"type":"string"},"required":true,"example":"My Projects"},"app_name":{"name":"app_name","description":"The name of your app. Every API-Token has a name to identify the purpose. The name of the app must be unique for every base.","in":"path","schema":{"type":"string"},"required":true,"example":"My App"},"external_link_token":{"name":"external_link_token","description":"The random string from the external link. Eg: \n- If the external link is https://cloud.seatable.io/dtable/external-links/c41cef71f5094827a786/, the link token is *c41cef71f5094827a786*.\n- If the external link is a custom link like https://cloud.seatable.io/dtable/external-links/custom/my-personal-link/, the link token is only *my-personal-link*.\n","in":"path","schema":{"type":"string"},"required":true,"example":"c41cef71f5094827a786"}},"schemas":{"AccountToken":{"type":"object","description":"The account token used for authenticating API requests.","properties":{"token":{"type":"string","example":"25285a3da6fff1f7a6f9c9abc8da12dcd2bd4470","minLength":40,"maxLength":40}}},"ApiTokenList":{"type":"object","description":"List of API tokens for a base.","properties":{"api_tokens":{"type":"array","items":{"$ref":"#/components/schemas/ApiToken"}}}},"ApiToken":{"type":"object","description":"api-token return object","properties":{"app_name":{"type":"string"},"api_token":{"type":"string","minLength":40,"maxLength":40},"generated_by":{"type":"string","format":"email"},"generated_at":{"type":"string","format":"date-time"},"last_access":{"type":"string","format":"date-time"},"permission":{"type":"string","enum":["","rw","r"]}},"example":{"app_name":"Example","api_token":"1234567f17157cd6c41fdb202813f8d9a9fi3yr7","generated_by":"123456600569491ba42905bf1647fd3f@auth.local","generated_at":"2021-03-02T09:47:41+00:00","last_access":"2021-03-02T09:47:41+00:00","permission":"rw"}},"ApiTokenTemporary":{"type":"object","description":"Temporary Api-Token, valid only for one hour","properties":{"api_token":{"type":"string"}},"example":{"api_token":"1234567iOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6IjhjYjJhNmRhNjU2OTQ5MWJhNDI5M1234567NDdmZDNmQGF1dGgubG9jYWwiLCJkdGFibGVfdXVpZCI6IjY1MGQ4YTBkLTdlMjctNDZhOC04YjE4LTZjYzZmM2RiMjA1NyIsImV4cCI6MTYxNDY4MjEyNi43ODY5MDE3fQ.FjRR-yur8lb0peiwD-h7j_gF97WXp17LS_n1HXipzKM"}},"AccessToken":{"type":"object","description":"Access Token","properties":{"access_token":{"type":"string"},"dtable_uuid":{"type":"string","format":"uuid"}},"example":{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MTQzNTI1OTQsImR0YWJsZV91dWlkIjoiNjUwZDhhMGQtN2UyNy00NmE4LThiMTgtNmNjNmYzZGIyMDU3IiwidXNlcm5hbWUiOiIiLCJwZXJtaXNzaW9uIjoicnciLCJhcHBfbmFtZSI6InBvc3RtYW4ifQ.4aTmvBfFElyB3xg5jjF7zWCiyRZI17SZD980GdHT6e3","dtable_uuid":"650d8a0d-7e27-46a8-8b18-6cc6f3db2057"}},"authentication_permission":{"type":"string","description":"- rw for read-write \n- r for read-only\n","enum":["","rw","r"],"default":""}}},"paths":{"/api2/auth-token/":{"post":{"tags":["Account-Token"],"summary":"Get Account-Token with Username and Password","operationId":"getAccountTokenfromUsername","description":"Generate an *Account-Token* with your username and password. This Account-Token is necessary for all the following account operations.\nUse the optional paramater if two-factor-authentication (2FA) is activated for your account.\n","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"Your email address"},"password":{"type":"string","description":"Your password"}},"required":["username","password"]}}}},"parameters":[{"$ref":"#/components/parameters/X-SEAFILE-OTP"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountToken"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"non_field_errors":["Unable to login with provided credentials."]}}}}},"security":[]}},"/api/v2.1/workspace/{workspace_id}/dtable/{base_name}/api-tokens/":{"get":{"tags":["API-Token"],"summary":"List API-Tokens","operationId":"listApiTokens","description":"List all *API-Tokens* of a base with additional informations like permission, generation date and last access time.\n","security":[{"AccountTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/workspace_id"},{"$ref":"#/components/parameters/base_name"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTokenList"},"example":{"api_tokens":[{"app_name":"My App","api_token":"4ed751818b040c85a49a2aff29f0176d032269fb","generated_by":"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6@auth.local","generated_at":"2021-03-02T09:47:41+00:00","last_access":"2021-03-02T09:47:41+00:00","permission":"rw"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"detail":"Invalid token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"detail":"Authentication credentials were not provided."}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"error_msg":"Workspace 99999 not found."}}}}}},"post":{"tags":["API-Token"],"summary":"Create API-Token","operationId":"createApiToken","description":"Create an *API-Token* for a base.\n","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"app_name":{"type":"string","description":"The name of your app. Every API-Token has a name to identify the purpose. The name of the app must be unique for every base.","example":"My App"},"permission":{"$ref":"#/components/schemas/authentication_permission"}},"required":["app_name","permission"]}}}},"security":[{"AccountTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/workspace_id"},{"$ref":"#/components/parameters/base_name"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiToken"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error_msg":"app_name invalid."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"detail":"Invalid token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"detail":"Authentication credentials were not provided."}}}}}}},"/api/v2.1/workspace/{workspace_id}/dtable/{base_name}/temp-api-token/":{"get":{"tags":["API-Token"],"summary":"Create API-Token (temporary)","operationId":"createTempApiToken","description":"Create a *temporary API-Token* for a base that expires after one hour.","security":[{"AccountTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/workspace_id"},{"$ref":"#/components/parameters/base_name"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTokenTemporary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"detail":"Invalid token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"detail":"Authentication credentials were not provided."}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"error_msg":"Workspace 99999 not found."}}}}}}},"/api/v2.1/workspace/{workspace_id}/dtable/{base_name}/api-tokens/{app_name}/":{"put":{"tags":["API-Token"],"summary":"Update API-Token","operationId":"updateApiToken","description":"Update the permission of an existing *API-Token*.","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"permission":{"$ref":"#/components/schemas/authentication_permission"}},"required":["permission"]}}}},"security":[{"AccountTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/workspace_id"},{"$ref":"#/components/parameters/base_name"},{"$ref":"#/components/parameters/app_name"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiToken"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"detail":"Invalid token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"detail":"Authentication credentials were not provided."}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"error_msg":"dtable <base_name> not found."}}}}}},"delete":{"tags":["API-Token"],"summary":"Delete API-Token","operationId":"deleteApiToken","description":"Delete one specific API token from a base. The token is identified by its *app_name*.","security":[{"AccountTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/workspace_id"},{"$ref":"#/components/parameters/base_name"},{"$ref":"#/components/parameters/app_name"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"detail":"Invalid token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"detail":"Authentication credentials were not provided."}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"error_msg":"dtable <base_name> not found."}}}}}}},"/api/v2.1/dtable/app-access-token/":{"get":{"tags":["Base-Token"],"summary":"Get Base-Token with API-Token","operationId":"getBaseTokenWithApiToken","description":"Generate a Base-Token with an API-Token. The API-Token grants either read or write permission to this base, depending of the permission of the API-Token.","security":[{"ApiTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/expiration_time"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"app_name":{"type":"string"},"access_token":{"type":"string"},"dtable_uuid":{"type":"string"},"dtable_server":{"type":"string"},"workspace_id":{"type":"integer"},"use_api_gateway":{"type":"boolean"},"dtable_name":{"type":"string"}}},"example":{"app_name":"postman","access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MTQzNTI1OTQsImR0YWJsZV91dWlkIjoiNjUwZDhhMGQtN2UyNy00NmE4LThiMTgtNmNjNmYzZGIyMDU3IiwidXNlcm5hbWUiOiIiLCJwZXJtaXNzaW9uIjoicnciLCJhcHBfbmFtZSI6InBvc3RtYW4ifQ.4aTmvBfFElyB3xg5jjF7zWCiyRZI17SZD980GdHT6e3","dtable_uuid":"650d8a0d-7e27-46a8-8b18-6cc6f3db2057","dtable_server":"https://cloud.seatable.io/api-gateway/","workspace_id":20,"use_api_gateway":true,"dtable_name":"Test base"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object"},"example":{"error_msg":"Permission denied."}}}}}}},"/api/v2.1/workspace/{workspace_id}/dtable/{base_name}/access-token/":{"get":{"tags":["Base-Token"],"summary":"Get Base-Token with Account-Token","operationId":"getBaseTokenWithAccountToken","description":"Generate a Base-Token using the user's Account-Token. The read/write permission depends on the user's access permissions to the base.","security":[{"AccountTokenAuth":[]}],"parameters":[{"$ref":"#/components/parameters/workspace_id"},{"$ref":"#/components/parameters/base_name"},{"$ref":"#/components/parameters/expiration_time"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessToken"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"detail":"Invalid token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"detail":"Authentication credentials were not provided."}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"error_msg":"dtable <base_name> not found."}}}}}}}}}