Download OpenAPI specification:Download
MythX is a security analysis API for Ethereum smart contracts. It powers tools that bring security into the smart contract SDLC.
Join the MythX community at MythX Discord for more information.
This document describes the API interface to MythX. It is entended for Dapp developers who wish to bring the power MythX to their Dapps.
The JSON Web Tokens authentication works this way:
Bearer
label, inside the request's Authorization
header; e.g.
Authorization
: Bearer JWT_ACCESS_TOKEN
.exp
value. Use
POST /auth/refresh to refresh a JWT pair.
Refresh tokens have one month expiration time.Security Scheme Type | HTTP |
---|---|
HTTP Authorization Scheme | bearer |
Bearer format | "JWT" |
Authentication scheme for MetaMask.
MetaMask SIGNED_CHALLENGE
.Security Scheme Type | HTTP |
---|---|
HTTP Authorization Scheme | digest |
MythX user roles and permissions are string tokens recognized by API server, and utilized to control user access to different API functionalities, as well as to alter API behavior for user with different rights.
User roles assigned to each user can be found inside the roles
array of user
object (see GET /users/{id}). Each role represents a
set of user permissions. The exact mapping between roles and permissions is
stored server-side and may be changed as needed, thus allowing to tune API
behavior for users with certain roles without chaning user roles.
When a user hits API, his roles are mapped into sets of permissions that correspond to these roles currently, and all these permissions are merged into a single permissions set. Endpoint controllers then check as necessary for the presence of required permissions in that set, to decide how different features should work for the user, or whether corresponding functionality should work for the user at all. To check permissions currently granted to the user by his roles use GET /users/{id}/permissions.
When a new JWT session is opened by POST /auth/login, it is possible to narrow down user permissions allowed for that session. For example, it allows to use JWT tokens as API keys for tools, that only allow to run analyses, and retrieve their results, but do not allow to modify user details, etc. To check user permissions requested, and granted in the current JWT session see GET /auth/session/permissions.
For convenience, GET /auth/login and GET /auth/refresh endpoints also return information on the permissions.
MythX Usage Allowances
NO_CACHE_LOOKUP
- Allows to use noCacheLookup
option in analysis
requests.ANALYSES_LOOKUP_OWN
- Permits to look up your own past analyses, using
GET /v1/analyses.Account Management Permissions
CREATE_USERS_ADMIN
- Allows to create new users with admin
role,
as well as grant / take this role for created accounts.CREATE_USERS_REGULAR
- Allows to create new regular users,
as well as grant / take this role for created accounts.CREATE_USERS_PARTNER
- Allows to create new users with parnter
role,
as well as grant / take this role for created accounts.CREATE_USERS_TRUSTED
- Allows to create new users with
the trusted_user
role, as well as grant / take this role for created
accounts.CREATE_USERS_WITHOUT_ROLES
- Allows to create new user accounts.CHANGE_PASSWORD_OWN
- Permits to change your own user password.USER_LOOKUP
- Allows to lookup accounts of other users.Misc Permissions
USERS_ANALYSES_STATS_LOOKUP
- Allows to fetch internal stats on MythX
usage and performance.Generates authentication challenge.
At least one of query parameters must be provided, and it will determine the type of challenge to generate. Currently, only challenges based on Ethereum address of the user are supported, for MetaMask authentication scheme. Additional challenge types might be added in future.
Challenge Types
ethAddress | string <Ethereum address> A valid Ethereum address. |
type | string Default: "one_time" Enum: "one_time" "short_lived" Type of the challenge to generate.
|
[- {
- "type": "string",
- "name": "string",
- "value": "string"
}, - {
- "type": "string",
- "name": "string",
- "value": "string"
}
]
Generates a pair of access and refresh JWT tokens for JWT authentication scheme.
It supports two operation modes, described below. In both modes,
jwtLifetimes.access
and jwtLifetimes.refresh
parameters of request body
allow to customize the lifetime of generated tokens. permissions
parameter
allows to narrow down
user permissions granted by API
for that session.
MetaMask login - follow
MetaMask authentication
to request and reply the authentication challenge. The challenge responce
should be passed to this login endpoint inside the Authorization
HTTP
header.
User credentials login - Login by username and password. The username may be either of:
password required | string <password> User password. A valid password is:
These rules are validated by password-validator using the following schema:
|
username | string User identifier. Can be either of:
|
object Custom JWT session lifetimes. Beware: Longer JWT lifetimes decrease session security. | |
permissions | Array of strings Items Enum: "ANALYSES_LOOKUP_OWN" "CHANGE_PASSWORD_OWN" "CREATE_USERS_ADMIN" "CREATE_USERS_REGULAR" "CREATE_USERS_PARTNER" "CREATE_USERS_TRUSTED" "CREATE_USERS_WITHOUT_ROLES" "USER_LOOKUP" "USERS_ANALYSES_STATS_LOOKUP" User permissions. For details see User Roles and Permission. |
ethAddress | string Deprecated An alias of |
userId | string Deprecated An alias of |
{- "password": "pa$$word",
- "username": "string",
- "jwtLifetimes": {
- "access": "10 mins",
- "refresh": "3 days"
}, - "permissions": [
- "ANALYSES_LOOKUP_OWN"
], - "ethAddress": "string",
- "userId": "string"
}
{- "jwtTokens": {
- "access": "string",
- "refresh": "string"
}, - "permissions": {
- "owned": [
- "ANALYSES_LOOKUP_OWN"
], - "requested": [
- "ANALYSES_LOOKUP_OWN"
], - "granted": [
- "ANALYSES_LOOKUP_OWN"
]
}, - "access": "string",
- "refresh": "string"
}
Closes the current API session, revoking JWT access token that signs this request, and the corresponding refresh token. Optional global parameter allows to close all user's sessions.
global | boolean Default: false If true all JWT tokens associated with the user will be revoked. |
{- "global": false
}
{ }
Generates a new pair of JWT authentication tokens (access and refresh), and revokes the current one. The new tokens will have the same lifetime and permissions as the old ones.
object (JWT Tokens) Holds a pair of JWT authentication tokens. | |
accessToken | string Deprecated JWT access token. |
refreshToken | string Deprecated JWT refresh token. |
{- "jwtTokens": {
- "access": "string",
- "refresh": "string"
}, - "accessToken": "string",
- "refreshToken": "string"
}
{- "jwtTokens": {
- "access": "string",
- "refresh": "string"
}, - "permissions": {
- "owned": [
- "ANALYSES_LOOKUP_OWN"
], - "requested": [
- "ANALYSES_LOOKUP_OWN"
], - "granted": [
- "ANALYSES_LOOKUP_OWN"
]
}, - "access": "string",
- "refresh": "string"
}
Retreives user permissions requested, and granted for the current JWT session. For details see User Roles and Permissions.
{- "owned": [
- "ANALYSES_LOOKUP_OWN"
], - "requested": [
- "ANALYSES_LOOKUP_OWN"
], - "granted": [
- "ANALYSES_LOOKUP_OWN"
]
}
Lists analyses groups.
To see his own groups, the user needs Analysis Groups
feature enabled.
dateFrom
and dateTo
parameters are defined in such way that query matches
any groups that were in progress between the specified timestamps.
offset | number Default: 0 Pagination offset (number of groups to skip). |
createdBy | string <MongoDB Object ID> Filter by MythX user ID of the group creator. |
groupName | string <= 256 Nullable Search by the group name. Partial match will be supported eventually, but is not implemented yet. |
dateFrom | string <date-time> Nullable List groups completed after this time. |
dateTo | string <date-time> Nullable List groups created before this time. |
mainSource | string Default: "" The JavaScript regular expression to match against the main source name. |
projectId | string <uuid> List groups belonging to the projectId |
{- "groups": [
- {
- "id": "string",
- "name": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": "string",
- "completedAt": "2019-08-24T14:15:22Z",
- "progress": 0,
- "status": "opened",
- "mainSourceFiles": [
- "string"
], - "numAnalyses": {
- "total": 0,
- "queued": 0,
- "running": 0,
- "failed": 0,
- "finished": 0
}, - "numVulnerabilities": {
- "high": 0,
- "medium": 0,
- "low": 0,
- "none": 0
}, - "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8"
}
], - "total": 0
}
Creates a new analysis group. Interrelated analyses can be added to a group
using the groupId
parameter of POST /analyses endpoint.
MythX platform provides additional analysis reporting features for groupped
analyses. The seal_group
command of POST /analysis-groups/{groupId}
endpoint seals the group, informing API that no further analyses will be
added to the group. For analyses submitted without groupId
, MythX
automatically creates sealed groups containing single analyses.
The ability to create analysis groups requires the Analysis Groups
feature enabled.
The request body payload is optional, and allows to provide additional meta information about the group.
groupName | string <= 256 Optional. User-specified group name. It can be a string, up to 256 symbols long, and must be unique amoung all groups previously created by the user. Empty string values are treated as no group name provided. |
{- "groupName": "string"
}
{- "id": "string",
- "name": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": "string",
- "completedAt": "2019-08-24T14:15:22Z",
- "progress": 0,
- "status": "opened",
- "mainSourceFiles": [
- "string"
], - "numAnalyses": {
- "total": 0,
- "queued": 0,
- "running": 0,
- "failed": 0,
- "finished": 0
}, - "numVulnerabilities": {
- "high": 0,
- "medium": 0,
- "low": 0,
- "none": 0
}, - "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8"
}
Gets analysis group by ID.
groupId required | string <MongoDB Object ID> Group ID. |
{- "id": "string",
- "name": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": "string",
- "completedAt": "2019-08-24T14:15:22Z",
- "progress": 0,
- "status": "opened",
- "mainSourceFiles": [
- "string"
], - "numAnalyses": {
- "total": 0,
- "queued": 0,
- "running": 0,
- "failed": 0,
- "finished": 0
}, - "numVulnerabilities": {
- "high": 0,
- "medium": 0,
- "low": 0,
- "none": 0
}, - "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8"
}
Executes specified operation on the analysis group.
seal_group
– Seals the group. API will forbid to add any new
analyses into the group, and it may peform some final operations on
the group reports, which are possible only after completion of all
analyses.
add_to_project
– Attaches specified group to the project
remove_from_project
– Detaches specified group from the previously attached project
groupId required | string <MongoDB Object ID> Group ID. |
type required | string Value: "seal_group" |
{- "type": "seal_group"
}
{- "id": "string",
- "name": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": "string",
- "completedAt": "2019-08-24T14:15:22Z",
- "progress": 0,
- "status": "opened",
- "mainSourceFiles": [
- "string"
], - "numAnalyses": {
- "total": 0,
- "queued": 0,
- "running": 0,
- "failed": 0,
- "finished": 0
}, - "numVulnerabilities": {
- "high": 0,
- "medium": 0,
- "low": 0,
- "none": 0
}, - "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8"
}
Get a PDF report for a given group. The PDF contains a list of vulnerabilities and other information about the submitted analyses and group itself. By default at success client will be redirected to the URL containing PDF report
groupId required | string <MongoDB Object ID> Group ID |
download_link | boolean Default: false Return JSON with download link instead of redirect. (Link's TTL is 5 minutes) |
share_link | boolean Default: false Return JSON with sharing link. (Link's TTL is 30 days) |
{
}
Lists analyses visible to the user, at most 20 records a time, sorted by submission time from the most recent to the oldest ones. Use offset query parameter for results pagination. Use dateFrom and dateTo query parameters to filter by analysis submission timestamps.
Dates are specified using ann ISO 8601 Date string
2018-11-20
,2018-11-20T23:13:12
,2018-11-20T23:13:12+00:00
2018-11-20T23:13:12.177Z
offset | integer <int32> Default: 0 Pagination offset. Number of records to skip. |
groupId | string <uuid> Nullable Analysis group ID. |
groupName | string <= 256 Nullable User-specified group name. |
dateFrom | string <date-time> Nullable Submission time filter. Restricts results to analyses submitted after this time. Unset by default. |
dateTo | string <date-time> Nullable Submission time filter. Restricts results to analyses submitted before this time. Unset by default. |
mainSource | string Default: "" The JavaScript regular expression to match against the main source name. |
{- "total": 2,
- "analyses": [
- {
- "apiVersion": "v1.3.0",
- "harveyVersion": "v0.1.0",
- "maruVersion": "v0.2.0",
- "mythrilVersion": "0.19.11",
- "queueTime": 1,
- "runTime": 300,
- "status": "Running",
- "submittedAt": "2019-01-10T01:29:38.410Z",
- "submittedBy": "000008544b0aa00010a91111",
- "uuid": "0680a1e2-b908-4c9a-a15b-636ef9b61486"
}, - {
- "apiVersion": "v1.3.0",
- "harveyVersion": "v0.1.0",
- "maruVersion": "v0.2.0",
- "mythrilVersion": "0.19.11",
- "queueTime": 0,
- "runTime": 0,
- "status": "Finished",
- "submittedAt": "2019-01-10T01:28:56.551Z",
- "submittedBy": "000008544b0aa00010a91111",
- "uuid": "78e3e82b-869d-4df1-8acf-cb1161281b71"
}
]
}
Submits Solidity contract(s) for vulnerability analysis and returns created analysis record. It is possible to conduct a partial analysis on a contract by only submitting its creation bytecode or its source code in their respective schema fields. Fill out both fields to conduct a complete analysis. The uuid field of the response should be used in subsequent calls to:
check analysis status, metadata, and the list of detected issues.
In addition to the JSON fields listed below, we allow additional fields. For example, truffle artfics will have an additional abi
attribute.
The request format is equivalent to the output of:
$ solc --pretty-json --combined-json ast,bin,bin-runtime,srcmap,srcmap-runtime
with the exception of the following field name changes which follow Truffe conventions:
bin
→ bytecode
bin-runtime
→ deployedBytecode
srcmap
→ sourceMap
srcmap-runtime
→ deployedSourceMap
required | Compete Analysis (object) or Bytecode Only (object) or Sourcecode Only (object) Expand |
clientToolName | string Optional. Name of the client tool sending the request. |
groupId | string <uuid> Default: "A new UUID generated by API" Analysis group ID. Grouped analyses can be retrieved from
GET /analyses using |
groupName | string <= 256 Default: "" Analysis group name. Grouped analyses can be retrieved from
GET /analyses using The default name (empty string) means no group name is provided. |
noCacheLookup | boolean Optional. When |
propertyChecking | boolean Default: false Only Assertion Violations Check enabling flag |
{- "clientToolName": "Sample MythX Client",
- "noCacheLookup": true,
- "data": {
- "bytecode": "6080604052348015600f57600080fd5b50603580601d6000396000f3fe6080604052600080fdfea165627a7a72305820be22e0bb5713cdec0be40f8c8f3804c27ee937114cbaaf21875ca0768207b3400029",
- "mainSource": "Token.sol",
- "sources": {
- "Token.sol": {
- "source": "pragma solidity >=0.4.22 <0.6.0;\\n\\ncontract Token {\\n}",
- "ast": {
- "absolutePath": "/Users/mirko/Desktop/consensys/sol/Token.sol",
- "exportedSymbols": {
- "Token": [
- 2
]
}, - "id": 3,
- "nodeType": "SourceUnit",
- "nodes": [
- {
- "id": 1,
- "literals": [
- "solidity",
- ">=",
- "0.4",
- ".22",
- "<",
- "0.6",
- ".0"
], - "nodeType": "PragmaDirective",
- "src": "0:32:0"
}, - {
- "baseContracts": [ ],
- "contractDependencies": [ ],
- "contractKind": "contract",
- "documentation": null,
- "fullyImplemented": true,
- "id": 2,
- "linearizedBaseContracts": [
- 2
], - "name": "Token",
- "nodeType": "ContractDefinition",
- "nodes": [ ],
- "scope": 3,
- "src": 123480
}
], - "src": "0:52:0"
}
}
}
}
}
{- "apiVersion": "v1.3.0",
- "harveyVersion": "v0.1.0",
- "maruVersion": "v0.2.0",
- "mythrilVersion": "0.19.11",
- "queueTime": 0,
- "status": "Queued",
- "submittedAt": "2019-01-10T01:29:38.410Z",
- "submittedBy": "000008544b0aa00010a91111",
- "uuid": "0680a1e2-b908-4c9a-a15b-636ef9b61486"
}
Gets status and metadata of for a prior
submit Smart Contract analysis request.
In the submission, a uuid was returned, which should be used in the url for
this request.
When analysis status is Finished
,
GET /analyses/{uuid}/issues may be
used to list detected vulnerabilities.
uuid required | string <uuid> analysis id |
{- "analysisMode": "full",
- "apiVersion": "string",
- "clientToolName": "string",
- "error": "string",
- "harveyVersion": "string",
- "mainSource": "string",
- "maruVersion": "string",
- "mythrilVersion": "string",
- "numSources": 0,
- "numVulnerabilities": {
- "high": 0,
- "medium": 0,
- "low": 0,
- "none": 0
}, - "queueTime": 0,
- "runTime": 0,
- "status": "Queued",
- "submittedAt": "2019-08-24T14:15:22Z",
- "submittedBy": "string",
- "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
- "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
- "groupName": "string",
- "propertyChecking": true,
- "info": "string"
}
Returns the input of a past analysis.
uuid required | string <uuid> analysis id |
object or string Optional query projection. It specifies which fields to include or exclude from the endpoint response. It can be either an URL-encoded string, or object. In the string form, it should be a whitespace-separated list of input
paths to include into the response, e.g. In the object form the inclusive, or exclusive projections should look
like |
{- "bytecode": "6080604052348015600f57600080fd5b50603580601d6000396000f3fe6080604052600080fdfea165627a7a72305820be22e0bb5713cdec0be40f8c8f3804c27ee937114cbaaf21875ca0768207b3400029",
- "mainSource": "Token.sol",
- "sources": {
- "Token.sol": {
- "source": "pragma solidity >=0.4.22 <0.6.0;\\n\\ncontract Token {\\n}",
- "ast": {
- "absolutePath": "/Users/mirko/Desktop/consensys/sol/Token.sol",
- "exportedSymbols": {
- "Token": [
- 2
]
}, - "id": 3,
- "nodeType": "SourceUnit",
- "nodes": [
- {
- "id": 1,
- "literals": [
- "solidity",
- ">=",
- "0.4",
- ".22",
- "<",
- "0.6",
- ".0"
], - "nodeType": "PragmaDirective",
- "src": "0:32:0"
}, - {
- "baseContracts": [ ],
- "contractDependencies": [ ],
- "contractKind": "contract",
- "documentation": null,
- "fullyImplemented": true,
- "id": 2,
- "linearizedBaseContracts": [
- 2
], - "name": "Token",
- "nodeType": "ContractDefinition",
- "nodes": [ ],
- "scope": 3,
- "src": 123480
}
], - "src": "0:52:0"
}
}
}
}
Lists issues detected during the analysis specified by UUID. Request will fail for unfinished analyses, use GET /analyses/{uuid} to verify the current analysis status.
IMPORTANT NOTE: Due to technical constraints, for some results the creation bytecode hash is returned inside the source list - instead of the original filename. Results concerning this hash can safely be excluded if they do not provide any additional value. This case usually happens when code is dynamically generated, e.g. inside the given contract's constructor.
uuid required | string <uuid> analysis id |
list_ignored | boolean Default: false Include ignored issues to the response. |
[- {
- "issues": [
- {
- "swcID": "SWC-103",
- "swcTitle": "Floating Pragma",
- "description": {
- "head": "A floating pragma is set.",
- "tail": "It is recommended to make a conscious choice on what version of Solidity is used for compilation. Currently any version equal or greater than \\\"0.4.24\\\" is allowed."
}, - "severity": "Low",
- "locations": [
- {
- "sourceMap": "48:1:0",
- "sourceType": "raw-bytecode",
- "sourceFormat": "evm-byzantium-bytecode",
- "sourceList": [
- "/test/my-super-safe-contract.sol"
]
}
], - "extra": { }
}
], - "sourceType": "solidity-file",
- "sourceFormat": "text",
- "sourceList": [
- "/test/my-super-safe-contract.sol"
], - "meta": { }
}
]
Get a PDF report for a given uuid. The PDF contains a list of vulnerabilities and other information about the submitted analysis. By default at success client will be redirected to the URL containing PDF report
uuid required | string <uuid> analysis id |
download_link | boolean Default: false Return JSON with download link instead of redirect. (Link's TTL is 5 minutes) |
share_link | boolean Default: false Return JSON with sharing link. (Link's TTL is 30 days) |
{
}
Lists projects.
offset | number Default: 0 Pagination offset (number of projects to skip). |
limit | number Default: 20 Projects to return. |
name | string Default: "" Filter projects by name |
{- "projects": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "created": "2019-08-24T14:15:22Z",
- "modified": "2019-08-24T14:15:22Z"
}
], - "total": 0
}
Creates a new project.
name required | string <= 256 User-specified project name. It can be a string, up to 256 symbols long, and must be unique amoung all projects previously created by the user. Empty string values are treated as no project name provided. |
description required | string Project description. |
groups | Array of strings <MongoDB Object ID> Group IDs to add to the project |
{- "name": "string",
- "description": "string",
- "groups": [
- "string"
]
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "created": "2019-08-24T14:15:22Z",
- "modified": "2019-08-24T14:15:22Z"
}
Gets project by ID.
projectId required | string <uuid> Project ID. |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "created": "2019-08-24T14:15:22Z",
- "modified": "2019-08-24T14:15:22Z"
}
Updates project
projectId required | string <uuid> Project ID. |
name | string <= 256 User-specified project name. It can be a string, up to 256 symbols long, and must be unique amoung all projects previously created by the user. |
description | string Project description. |
{- "name": "string",
- "description": "string"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "description": "string",
- "created": "2019-08-24T14:15:22Z",
- "modified": "2019-08-24T14:15:22Z"
}
Updates badge preferences for the project
projectId required | string <uuid> Project ID. |
active | boolean Activate (or deactivate) badge for the project |
{- "active": true
}
{- "active": true
}
Lists registered API users. Allows to lookup users by email and Ethereum addresses.
For users with no USER_LOOKUP
permission this endpoint only finds their
own user objects.
Returns at most 20 users in a single response. Use the offset
query
parameter for pagination.
offset | integer Default: 0 Pagination offset. The number of records to skip. |
orderBy | string Default: "email" Value: "email" User ordering. |
string Default: null Filter user by email fragment. | |
ethAddress | string Default: null Filter users by Ethereum address fragments. |
string or Array of strings Filter users by API roles, stored in DB (does not account for any additional roles given temporarily by subscriptions, etc.). |
{- "total": 0,
- "users": [
- {
- "id": "string",
- "createdAt": "2019-08-24",
- "createdBy": "string",
- "createdByPartner": true,
- "creatorLabel": "",
- "ethAddress": "string",
- "label": "string",
- "mustChangePassword": true,
- "ownerPartnerId": "string",
- "ownerPartnerLabel": "",
- "privateLabel": "string",
- "preferences": {
- "newsletter": false,
- "serviceNotifications": true
}, - "roles": [
- "string"
], - "subscriptionId": "string",
- "termsId": "no_terms"
}
]
}
Creates a new user.
Creation of a new user by a parent user.
The parent user must have necessary permissions
(GET /v1/users/{id}/permissions).
Currently, CREATE_USERS_ADMIN
, CREATE_USERS_REGULAR
,
CREATE_USERS_TRUSTED
, and
CREATE_USERS_WITHOUT_ROLES
permissions allow to create users with
corresponding roles, as well as further give and take corresponding
roles of created users.
The only obligatory request field is the password
to set on the created
user account.
Self-registration
This endpoint allows users to self-register at MythX Website. There are 2 options available:
If the MetaMask authentication scheme is used then the second option becomes implicitly selected.
Without MetaMask
As no ethAddress
is provided a new user will be created without any attached ethAddress
(one can attach it later).
In this case it is obligatory to provide at least the following required
parameters: password
(to set on the created user account), termsId
, and gReCaptcha
.
email
, if provided, must be unique among registered users.
It won't be used by API until verification
(the exact details to be added).
With MetaMask
A new user will be attached ethAddress
provided by MetaMask authentication scheme.
In this case it is obligatory to provide at least the following required parameters:
password
(to set on the created user account), termsId
,
and gReCaptcha
.
email
, if provided, must be unique among registered users.
It won't be used by API until verification
(the exact details to be added).
password required | string <password> User password. A valid password is:
These rules are validated by password-validator using the following schema:
|
string <email> Email. Must be unique among already registered users. | |
ethAddress | string <Ethereum Address> User's ethereum address. |
label | string <= 256 characters Optional label, visible to the user, and editable by the user. It is also exposed to the users created by this user as |
ownerPartnerId | string <MongoDB ObjectID> ID of the partner account associated with this user. Analyses executed by the newly created user will be counted for that parnter for billing and book-keeping purposes. Requires |
privateLabel | string <= 256 characters Optional label, invisible to the user. This label is only visible to, and editable by MythX admins, and also to users up in the user tree (i.e. those who created this user, those who created them, etc.) |
object (User Preferences) Generic user preferences. | |
roles | Array of strings The following user roles exist in MythX plaform as of now:
|
{- "password": "pa$$word",
- "ethAddress": "string",
- "label": "string",
- "ownerPartnerId": "string",
- "privateLabel": "string",
- "preferences": {
- "newsletter": false,
- "serviceNotifications": true
}, - "roles": [
- "string"
]
}
{- "id": "string",
- "createdAt": "2019-08-24",
- "createdBy": "string",
- "createdByPartner": true,
- "creatorLabel": "",
- "ethAddress": "string",
- "label": "string",
- "mustChangePassword": true,
- "ownerPartnerId": "string",
- "ownerPartnerLabel": "",
- "privateLabel": "string",
- "preferences": {
- "newsletter": false,
- "serviceNotifications": true
}, - "roles": [
- "string"
], - "subscriptionId": "string",
- "termsId": "no_terms"
}
Initializes password recovery via email. Requires user email set and verified. If so, it sends an email with recovery link to that address.
email required | string <email> User email address. Note that operation will be success even when a non-existing email is provided, and no recovery email have been sent. This is to prevent using this endpoint for scanning registered emails. |
gReCaptcha required | string Google ReCaptcha code. |
{- "gReCaptcha": "string"
}
{ }
Sends verification email.
email required | string <email> User email address. Note that operation will be success even when a non-existing email is provided or it was already verified. This is to prevent using this endpoint for scanning registered emails. |
{- "email": "[email protected]"
}
{ }
Gets user object by user ID.
id required | string <MongoDB Object ID> User ID. |
{- "id": "string",
- "createdAt": "2019-08-24",
- "createdBy": "string",
- "createdByPartner": true,
- "creatorLabel": "",
- "ethAddress": "string",
- "label": "string",
- "mustChangePassword": true,
- "ownerPartnerId": "string",
- "ownerPartnerLabel": "",
- "privateLabel": "string",
- "preferences": {
- "newsletter": false,
- "serviceNotifications": true
}, - "roles": [
- "string"
], - "subscriptionId": "string",
- "termsId": "no_terms"
}
Executes one of generic operations on the specified user account:
Change Password allows to change user password. Password must be different from previously used passwords.
This function supports a direct login with user credentials, hence
the optional password
and username
fields in the request. They
work the same as they would in
POST /auth/login.
This function has two operation modes:
Initialization of Email Verification: (re-)starts email verification flow. API will check that user email is set, reset its status to to unverified, and send an email with the verification link to the user's email.
Update User Details allows to update:
Requires JWT or MetaMask authentication. Currently, it only allows to change your own details only.
Update User Preferences allows to update:
Change Ethereum Address allows to update (or set if initially one was not set) user's corresponding ethAddress
.
Remove Ethereum Address allows to remove user's corresponding ethAddress
.
id required | string <MongoDB Object ID> User ID. |
type required | string Value: "change_password" |
newPassword required | string <password> User password. A valid password is:
These rules are validated by password-validator using the following schema:
|
resetCode | string <uuid> Optional. Password reset code, issued by a previous call to POST /users/password-recovery. When provided, authentication is not required by this action. |
password | string <password> User password. A valid password is:
These rules are validated by password-validator using the following schema:
|
username | string User identifier. Can be either of:
|
ethAddress | string Deprecated An alias of |
userId | string Deprecated An alias of |
{- "type": "change_password",
- "newPassword": "pa$$word",
- "resetCode": "1517d93a-966f-4cf9-a208-a0400b6edce7",
- "password": "pa$$word",
- "username": "string",
- "ethAddress": "string",
- "userId": "string"
}
{- "id": "string",
- "createdAt": "2019-08-24",
- "createdBy": "string",
- "createdByPartner": true,
- "creatorLabel": "",
- "ethAddress": "string",
- "label": "string",
- "mustChangePassword": true,
- "ownerPartnerId": "string",
- "ownerPartnerLabel": "",
- "privateLabel": "string",
- "preferences": {
- "newsletter": false,
- "serviceNotifications": true
}, - "roles": [
- "string"
], - "subscriptionId": "string",
- "termsId": "no_terms"
}
Returns the array of permissions given to the specified user by his roles. For the current user and JWT session the actual permissions can be narrowed down at the time of session initiation, the endpoint GET /auth/permissions returns the array of permissions granted for the current user session.
See also User Roles and Permissions.
id required | string User ID. |
[- "ANALYSES_LOOKUP_OWN"
]
Serves real-time and historic statistics on API usage. The heavy-lifting calculation of stats is done continiously by a background API thread, and the results are stored to the database. This endpoint just looks up for requested records already existing in the database, and returns up to 25 of them (pagination is supported). Results are sorted and served chronologically from the most recent to the oldest ones.
For most of the time API will keep all statistics fresh, outdated at most by ~1 minute from the current moment. Larger lags are possible when a newly deployed API version triggers re-evaluation of past statistics. In that case the real-time updates of recent stats are paused until the re-evaluation is completed. By design, this does not cause any data loses.
type required | string Enum: "partners" "users-analyses" The type of stats to return.
|
interval | string Default: "LIFE_TIME" Enum: "LIFE_TIME" "ONE_YEAR" "ONE_MONTH" "ONE_DAY" "ONE_HOUR" "FIVE_MINUTES" Stats interval, i.e the time range covered by a single record in
the response. In other words, requesting For a reasonalbe use of database space, daily stats are available for ~3 last years, hourly stats for ~1 last month, five-minutes stats for ~3 last days. |
from | string <date> Filters requested statistics records by their interval start,
i.e. all returned objects will describe intervals starting after
|
to | string <date> Filters requested statistics records by their interval starts,
i.e. all returned objects will describe intervals starting prior
|
skip | number <int> Response pagination: the specified number of records will be omitted from the response (matching records in the response are sorted chronologically from the most recent to the oldest). |
minRevision | number <int> Specifies the minimal revision number of stat records that may be included into the response. See description of response format for the meaning of revision number. In practice, statistics records of the same type and with different revisions may co-exist only shortly after an API redeployment that caused re-evaluation of past stats data. Once re-evaluation is completed, all existing records of that type end up updated to the latest revision. |
[- {
- "from": "2018-01-01T00:00:00.000Z",
- "interval": "LIFE_TIME",
- "createdAt": "2019-03-31T22:09:27.684Z",
- "type": "USERS_ANALYSES",
- "revision": 9,
- "data": {
- "numUsers": {
- "registered": {
- "total": 371,
- "new": 371,
- "activeIn5min": 0.21033004972474095,
- "activeInHour": 2.523960596696891,
- "activeInDay": 60.55527076341195
}, - "trial": {
- "activeIn5min": 0.004182634802378998,
- "activeInHour": 0.05019161762854797,
- "activeInDay": 1.1452481511448245
}
}, - "numAnalyses": {
- "requested": {
- "total": 146861,
- "new": 146861
}, - "cacheHits": {
- "total": 38015,
- "new": 38015
}, - "failed": {
- "total": 4310,
- "new": 4310,
- "inProgress": {
- "total": 4272,
- "new": 4272
}, - "inQueue": {
- "total": 38,
- "new": 38
}
}, - "finished": {
- "total": 104533,
- "new": 104533
}, - "queued": {
- "total": 0,
- "new": 108846
}, - "inProgress": {
- "total": 3,
- "new": 108808
}, - "byUserType": {
- "registered": {
- "total": 122313,
- "new": 122313
}, - "trial": {
- "total": 24548,
- "new": 24548
}
}
}, - "analysis": {
- "time": {
- "queue": {
- "av": "164113.69278836806,",
- "max": "20303,",
- "avMin": "2.7352282131394676,",
- "maxMin": 0.3383833333333333
}, - "av": "215796.1882000488,",
- "max": "65806,",
- "avMin": "3.59660313666748,",
- "maxMin": 1.0967666666666667
}
}
}
}
]