# Custom authentication Use the endpoints described below when you need to execute API requests on behalf of other Filemail accounts. This can be useful when creating an app/UI that integrates with Filemail infrastructure, but requires other users to authenticate. Typical flow: 1. Use the [#post-auth-login](#post-auth-login "mention") providing user email and password. 2. Store the resulting `refreshtoken` for later use in a secure place (it is valid for 3 months). The resulting `logintoken` (valid for 7 days) should be used to authenticate further requests. 3. Include both `x-api-key` and `logintoken` in the request headers: 4. ``` x-api-key: mJE5v1zHs.... logintoken: r9BPAFW..... ``` 5. When you issue a request with an expired `logintoken` the server will return `401` HTTP status code. In that case use the `refreshtoken` and the [#post-auth-refreshtoken](#post-auth-refreshtoken "mention") endpoint to create a new `logintoken`. Note that the `refreshtoken` can be used only once. You will also get a new `refreshtoken` in the response every time you call [#post-auth-refreshtoken](#post-auth-refreshtoken "mention"). ## POST /auth/login > Authenticate as a Filemail user. This operation generates a short-lived (7 days) logintoken and a long-lasting (3 months) refreshtoken. The refreshtoken can be later used to obtain a new logintoken. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Auth"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/auth/login":{"post":{"tags":["Auth"],"description":"Authenticate as a Filemail user. This operation generates a short-lived (7 days) logintoken and a long-lasting (3 months) refreshtoken. The refreshtoken can be later used to obtain a new logintoken.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/LoginDtoBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/LoginDtoBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/LoginDtoBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"429":{"description":"Too Many Requests","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"LoginRequest":{"required":["email","password"],"type":"object","properties":{"email":{"minLength":1,"type":"string","description":"Email of the user."},"password":{"minLength":1,"type":"string","description":"Password matching the user email."}},"additionalProperties":false},"LoginDtoBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/LoginDto"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"LoginDto":{"required":["logintoken","logintokenExpireDate","refreshtoken"],"type":"object","properties":{"logintoken":{"minLength":1,"type":"string","description":"Login token. Append it to HTTP requests as `logintoken` header to issue authenticated requests."},"logintokenExpireDate":{"type":"integer","description":"Login token expiration date represented as unix time in milliseconds.","format":"int64"},"refreshtoken":{"minLength":1,"type":"string","description":"A one-time-use refresh token. Use it issue a new logintoken (and also a new refreshtoken). Default lifetime of this token is 3 months."},"twoFactorToken":{"type":"string","description":"This token is used only when setting up Multi-Factor-Authentication.","nullable":true},"signInStatus":{"$ref":"#/components/schemas/SignInStatus"}},"additionalProperties":false},"SignInStatus":{"enum":["NotAuthorized","Authorized","CaptchaRequired","PinRequired","SetupRequired"],"type":"string"},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` ## POST /auth/logout > Logout a Filemail user. This operation destroys the logintoken provided in the \`logintoken\` header and the associated refreshtoken. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Auth"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/auth/logout":{"post":{"tags":["Auth"],"description":"Logout a Filemail user. This operation destroys the logintoken provided in the `logintoken` header and the associated refreshtoken.","parameters":[{"name":"allDevices","in":"query","description":"When set to `true` all the user's logintokens and refreshtokens will be destroyed.","schema":{"type":"boolean","description":"When set to `true` all the user's logintokens and refreshtokens will be destroyed."}},{"name":"logintoken","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/BaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` ## POST /auth/refreshtoken > Generates new logintoken and a new refreshtoken based on an existing refreshtoken (obtained in the \`login\` operation). The provided refreshtoken will be destroyed. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Auth"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/auth/refreshtoken":{"post":{"tags":["Auth"],"description":"Generates new logintoken and a new refreshtoken based on an existing refreshtoken (obtained in the `login` operation). The provided refreshtoken will be destroyed.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/RefreshTokenDtoBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenDtoBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenDtoBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"RefreshTokenRequest":{"type":"object","properties":{"refreshtoken":{"type":"string","description":"A one-time-use refreshtoken obtained from the `login` endpoint."}},"additionalProperties":false},"RefreshTokenDtoBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/RefreshTokenDto"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"RefreshTokenDto":{"type":"object","properties":{"logintoken":{"type":"string","nullable":true},"logintokenExpireDate":{"type":"integer","description":"Login token expiration date represented as unix time in milliseconds.","format":"int64","nullable":true},"refreshtoken":{"type":"string","nullable":true}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` --- # 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://docs.filemail.com/custom-authentication.md?ask= ``` 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.