MythX API (v1.9)

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.

API Authentication Methods

MythX API implements JWT and MetaMask authentication schemes. For better security user credentials (User ID / Ethereum address / email + password) are only used to start JWT sessions

JWT

The JSON Web Tokens authentication works this way:

  • Use POST /auth/login to generate a pair of JWT access and refresh tokens, and thus to start a JWT session.
  • To authenticate following API calls pass the access token, prefixed by Bearer label, inside the request's Authorization header; e.g. Authorization: Bearer JWT_ACCESS_TOKEN.
  • Access tokens are valid for ten minutes. To check a token's expiration timestamp decode the token, and check its exp value. Use POST /auth/refresh to refresh a JWT pair. Refresh tokens have one month expiration time.
  • To invalidate active JWT pair, and thus to terminate a JWT session use POST /auth/logout.
Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

MetaMask

Authentication scheme for MetaMask.

  • Get authentication challenge with GET /auth/challenge;
  • Sign it with MetaMask;
  • Pass the signed message via the Authorization HTTP header of the next request to a protected API endpoint. The header value must follow the format MetaMask SIGNED_CHALLENGE.
Security Scheme Type HTTP
HTTP Authorization Scheme digest

User Roles and Permissions

Overview

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.

Valid User 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.

Authentication Calls

Auth challenge

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

  • Challenge based on Ethereum address. Generated when ethAddress query parameter is provided.
query Parameters
ethAddress
string <Ethereum address>

A valid Ethereum address.

type
string
Default: "one_time"
Enum: "one_time" "short_lived"

Type of the challenge to generate.

  • one_time allows just a single use of challenge response for authentication of a subsequent API call, within 10 minutes after generation of the challenge. After the first use the challenge is revoked. It is also revoked if not used within 10 minutes.

  • short_lived allows to use the challenge response unlimited number of times within 10 minutes after the challenge generation.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

API login

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:

    • MythX User ID (assigned by MythX API to any registered user);
    • Ethereum address, if user account is associated with an address;
    • A verified email address, if user account is associated with an email address, and that address has been verified by visiting the verification link in the verification email sent by API each time when user email is set or modified.
Authorizations:
Request Body schema: application/json
One of
password
required
string <password>

User password.

A valid password is:

  • Between 8 and 64 symbols long (both inclusive);
  • Contains at least one lowercase (a-z) and uppercase (A-Z) letter;
  • Contains at least one digit (0-9);
  • Contains at least one of these symbols:
    `~!@#$%^&*()-_=+[{}]\|;:'",<.>/?€£¥₹
  • Does not contain whitespaces.

These rules are validated by password-validator using the following schema:

const MIN_PASSWORD_LENGTH = 8;
const MAX_PASSWORD_LENGTH = 64;
const passwordSchema = new PasswordValidator();
  passwordSchema
    .is().min(MIN_PASSWORD_LENGTH)
    .is().max(MAX_PASSWORD_LENGTH)
    .has().uppercase()
    .has().lowercase()
    .has().digits()
    .has().symbols()
    .has().not().spaces();
username
string

User identifier. Can be either of:

  • User Ethereum address;
  • A verified user email;
  • MythX user ID.
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 username for backward compatibility.

userId
string
Deprecated

An alias of username for backward compatibility.

Responses

Request samples

Content type
application/json
Example
{
  • "password": "pa$$word",
  • "username": "string",
  • "jwtLifetimes": {
    },
  • "permissions": [
    ],
  • "ethAddress": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "jwtTokens": {
    },
  • "permissions": {
    },
  • "access": "string",
  • "refresh": "string"
}

API logout

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.

Authorizations:
Request Body schema: application/json
global
boolean
Default: false

If true all JWT tokens associated with the user will be revoked.

Responses

Request samples

Content type
application/json
{
  • "global": false
}

Response samples

Content type
application/json
{ }

Refresh Auth Tokens

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.

Request Body schema: application/json
object (JWT Tokens)

Holds a pair of JWT authentication tokens.

accessToken
string
Deprecated

JWT access token.

refreshToken
string
Deprecated

JWT refresh token.

Responses

Request samples

Content type
application/json
{
  • "jwtTokens": {
    },
  • "accessToken": "string",
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "jwtTokens": {
    },
  • "permissions": {
    },
  • "access": "string",
  • "refresh": "string"
}

Session Permissions

Retreives user permissions requested, and granted for the current JWT session. For details see User Roles and Permissions.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "owned": [
    ],
  • "requested": [
    ],
  • "granted": [
    ]
}

Security Analysis

List Analysis Groups

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.

query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "total": 0
}

Create Analysis Group

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.

Authorizations:
Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "groupName": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "progress": 0,
  • "status": "opened",
  • "mainSourceFiles": [
    ],
  • "numAnalyses": {
    },
  • "numVulnerabilities": {
    },
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8"
}

Analysis Group by ID

Gets analysis group by ID.

Authorizations:
path Parameters
groupId
required
string <MongoDB Object ID>

Group ID.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "progress": 0,
  • "status": "opened",
  • "mainSourceFiles": [
    ],
  • "numAnalyses": {
    },
  • "numVulnerabilities": {
    },
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8"
}

Analysis Group Operation

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

Authorizations:
path Parameters
groupId
required
string <MongoDB Object ID>

Group ID.

Request Body schema: application/json
One of
type
required
string
Value: "seal_group"

Responses

Request samples

Content type
application/json
Example
{
  • "type": "seal_group"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "progress": 0,
  • "status": "opened",
  • "mainSourceFiles": [
    ],
  • "numAnalyses": {
    },
  • "numVulnerabilities": {
    },
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8"
}

Delete Analysis Group

Deletes analysis group

Authorizations:
path Parameters
groupId
required
string <MongoDB Object ID>

Group ID.

Responses

Response samples

Content type
text/plain
OK

Get PDF Report for Analyses Group

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

Authorizations:
path Parameters
groupId
required
string <MongoDB Object ID>

Group ID

query Parameters
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)

Responses

Response samples

Content type
application/json
Example

List Past Analyses

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

Example Date Strings

  • 2018-11-20,
  • 2018-11-20T23:13:12,
  • 2018-11-20T23:13:12+00:00
  • 2018-11-20T23:13:12.177Z
Authorizations:
query Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "total": 2,
  • "analyses": [
    ]
}

Submit Smart Contract for analysis

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:

  • binbytecode
  • bin-runtimedeployedBytecode
  • srcmapsourceMap
  • srcmap-runtimedeployedSourceMap
Authorizations:
Request Body schema: application/json
required
Compete Analysis (object) or Bytecode Only (object) or Sourcecode Only (object)

Expand data to view full schema.

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 groupId query parameter. If no group ID is specified, a random unique one will be generated by API itself. Must match a group created beforehand by POST /analysis-groups

groupName
string <= 256
Default: ""

Analysis group name. Grouped analyses can be retrieved from GET /analyses using groupName query parameter. The group with this name is automatically created, if user has analysis grouping permission, otherwise analysis is added to the group (must be non-sealed).

The default name (empty string) means no group name is provided.

noCacheLookup
boolean

Optional. When true API won't look into the cache of past analyses, and always will run a new analysis for this request. The using of cache has no other side effects beside saving the runtime, thus this option is intended only for benchmarking, API health control, and debuging purposes. Itrequries NO_CACHE_LOOKUP permission to use, which is granted only to MythX team members.

propertyChecking
boolean
Default: false

Only Assertion Violations Check enabling flag

Responses

Request samples

Content type
application/json
Example
{
  • "clientToolName": "Sample MythX Client",
  • "noCacheLookup": true,
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "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"
}

Analysis Status

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.

Authorizations:
path Parameters
uuid
required
string <uuid>

analysis id

Responses

Response samples

Content type
application/json
{
  • "analysisMode": "full",
  • "apiVersion": "string",
  • "clientToolName": "string",
  • "error": "string",
  • "harveyVersion": "string",
  • "mainSource": "string",
  • "maruVersion": "string",
  • "mythrilVersion": "string",
  • "numSources": 0,
  • "numVulnerabilities": {
    },
  • "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"
}

Analysis Input

Returns the input of a past analysis.

Authorizations:
path Parameters
uuid
required
string <uuid>

analysis id

query Parameters
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. bytecode mainSource. Alternatively, it can be a list of input paths to exclude from the response, if the paths are prefixed by -, e.g. -mainSource -sources. The value must be either entirely inclusive, or exclusive, and it must be URL encoded as an URL query parameter.

In the object form the inclusive, or exclusive projections should look like {"bytecode": 1, "mainSource": 1}, and {"mainSource": 0, "sources": 0}. Some more complex projection operations are supported, following the MongoDB projection syntax.

Responses

Response samples

Content type
application/json
Example
{
  • "bytecode": "6080604052348015600f57600080fd5b50603580601d6000396000f3fe6080604052600080fdfea165627a7a72305820be22e0bb5713cdec0be40f8c8f3804c27ee937114cbaaf21875ca0768207b3400029",
  • "mainSource": "Token.sol",
  • "sources": {
    }
}

Detected issues

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.

Authorizations:
path Parameters
uuid
required
string <uuid>

analysis id

query Parameters
list_ignored
boolean
Default: false

Include ignored issues to the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get PDF Report for Analysis

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

Authorizations:
path Parameters
uuid
required
string <uuid>

analysis id

query Parameters
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)

Responses

Response samples

Content type
application/json
Example

Projects

List Projects

Lists projects.

Authorizations:
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "projects": [
    ],
  • "total": 0
}

Create Project

Creates a new project.

Authorizations:
Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z"
}

Project by ID

Gets project by ID.

Authorizations:
path Parameters
projectId
required
string <uuid>

Project ID.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z"
}

Update Project

Updates project

Authorizations:
path Parameters
projectId
required
string <uuid>

Project ID.

Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z"
}

Delete Project

Deletes project

Authorizations:
path Parameters
projectId
required
string <uuid>

Project ID.

Responses

Response samples

Content type
text/plain
OK

Badge Preferences

Gets badge preferences for the project

Authorizations:
path Parameters
projectId
required
string <uuid>

Project ID.

Responses

Response samples

Content type
application/json
{
  • "active": true
}

Update Badge Preferences

Updates badge preferences for the project

Authorizations:
path Parameters
projectId
required
string <uuid>

Project ID.

Request Body schema: application/json
active
boolean

Activate (or deactivate) badge for the project

Responses

Request samples

Content type
application/json
{
  • "active": true
}

Response samples

Content type
application/json
{
  • "active": true
}

Badge Data

Gets badge data to generate the actual badge (using badgen.net service)

path Parameters
projectId
required
string <uuid>

Project ID.

Responses

Response samples

Content type
application/json
{
  • "subject": "MythX",
  • "status": "n/a",
  • "color": "gray"
}

User Accounts

List of users

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.

Authorizations:
query Parameters
offset
integer
Default: 0

Pagination offset. The number of records to skip.

orderBy
string
Default: "email"
Value: "email"

User ordering.

email
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.).

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "users": [
    ]
}

Create a new user

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:

    • Self-registration without Metamask
    • Self-registration with Metamask

    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).

Authorizations:
Request Body schema: application/json
One of
password
required
string <password>

User password.

A valid password is:

  • Between 8 and 64 symbols long (both inclusive);
  • Contains at least one lowercase (a-z) and uppercase (A-Z) letter;
  • Contains at least one digit (0-9);
  • Contains at least one of these symbols:
    `~!@#$%^&*()-_=+[{}]\|;:'",<.>/?€£¥₹
  • Does not contain whitespaces.

These rules are validated by password-validator using the following schema:

const MIN_PASSWORD_LENGTH = 8;
const MAX_PASSWORD_LENGTH = 64;
const passwordSchema = new PasswordValidator();
  passwordSchema
    .is().min(MIN_PASSWORD_LENGTH)
    .is().max(MAX_PASSWORD_LENGTH)
    .has().uppercase()
    .has().lowercase()
    .has().digits()
    .has().symbols()
    .has().not().spaces();
email
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 creatorLabel field in their user objects.

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 SET_USER_OWNER_PARNTER_ID permission to set.

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:

  • admin - Gives all possible permissions. It is only intended for core members of MythX team.

  • regular_user - Gives permission for regular API usage.

  • partner - Gives permission to create new privileged and regular users.

  • trusted_user - Gives permission to fetch internal platform usage statistics.

Responses

Request samples

Content type
application/json
Example
{
  • "password": "pa$$word",
  • "email": "[email protected]",
  • "ethAddress": "string",
  • "label": "string",
  • "ownerPartnerId": "string",
  • "privateLabel": "string",
  • "preferences": {
    },
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24",
  • "createdBy": "string",
  • "createdByPartner": true,
  • "creatorLabel": "",
  • "email": {},
  • "ethAddress": "string",
  • "label": "string",
  • "mustChangePassword": true,
  • "ownerPartnerId": "string",
  • "ownerPartnerLabel": "",
  • "privateLabel": "string",
  • "preferences": {
    },
  • "roles": [
    ],
  • "subscriptionId": "string",
  • "termsId": "no_terms"
}

Password Recovery

Initializes password recovery via email. Requires user email set and verified. If so, it sends an email with recovery link to that address.

Authorizations:
Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{ }

Send Verification Email

Sends verification email.

Authorizations:
Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{ }

User Object By ID

Gets user object by user ID.

Authorizations:
path Parameters
id
required
string <MongoDB Object ID>

User ID.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24",
  • "createdBy": "string",
  • "createdByPartner": true,
  • "creatorLabel": "",
  • "email": {},
  • "ethAddress": "string",
  • "label": "string",
  • "mustChangePassword": true,
  • "ownerPartnerId": "string",
  • "ownerPartnerLabel": "",
  • "privateLabel": "string",
  • "preferences": {
    },
  • "roles": [
    ],
  • "subscriptionId": "string",
  • "termsId": "no_terms"
}

User account action

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:

    • Authenticated call to change user password;
    • A call without authentication, which provides a reset code issued previously by POST /users/password-recovery call.
  • 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:

    • User first name;
    • User last name;

    Requires JWT or MetaMask authentication. Currently, it only allows to change your own details only.

  • Update User Preferences allows to update:

    • Newsletter Subscription
  • 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.

Authorizations:
path Parameters
id
required
string <MongoDB Object ID>

User ID.

Request Body schema: application/json
One of
type
required
string
Value: "change_password"
newPassword
required
string <password>

User password.

A valid password is:

  • Between 8 and 64 symbols long (both inclusive);
  • Contains at least one lowercase (a-z) and uppercase (A-Z) letter;
  • Contains at least one digit (0-9);
  • Contains at least one of these symbols:
    `~!@#$%^&*()-_=+[{}]\|;:'",<.>/?€£¥₹
  • Does not contain whitespaces.

These rules are validated by password-validator using the following schema:

const MIN_PASSWORD_LENGTH = 8;
const MAX_PASSWORD_LENGTH = 64;
const passwordSchema = new PasswordValidator();
  passwordSchema
    .is().min(MIN_PASSWORD_LENGTH)
    .is().max(MAX_PASSWORD_LENGTH)
    .has().uppercase()
    .has().lowercase()
    .has().digits()
    .has().symbols()
    .has().not().spaces();
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:

  • Between 8 and 64 symbols long (both inclusive);
  • Contains at least one lowercase (a-z) and uppercase (A-Z) letter;
  • Contains at least one digit (0-9);
  • Contains at least one of these symbols:
    `~!@#$%^&*()-_=+[{}]\|;:'",<.>/?€£¥₹
  • Does not contain whitespaces.

These rules are validated by password-validator using the following schema:

const MIN_PASSWORD_LENGTH = 8;
const MAX_PASSWORD_LENGTH = 64;
const passwordSchema = new PasswordValidator();
  passwordSchema
    .is().min(MIN_PASSWORD_LENGTH)
    .is().max(MAX_PASSWORD_LENGTH)
    .has().uppercase()
    .has().lowercase()
    .has().digits()
    .has().symbols()
    .has().not().spaces();
username
string

User identifier. Can be either of:

  • User Ethereum address;
  • A verified user email;
  • MythX user ID.
ethAddress
string
Deprecated

An alias of username for backward compatibility.

userId
string
Deprecated

An alias of username for backward compatibility.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "change_password",
  • "newPassword": "pa$$word",
  • "resetCode": "1517d93a-966f-4cf9-a208-a0400b6edce7",
  • "password": "pa$$word",
  • "username": "string",
  • "ethAddress": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24",
  • "createdBy": "string",
  • "createdByPartner": true,
  • "creatorLabel": "",
  • "email": {},
  • "ethAddress": "string",
  • "label": "string",
  • "mustChangePassword": true,
  • "ownerPartnerId": "string",
  • "ownerPartnerLabel": "",
  • "privateLabel": "string",
  • "preferences": {
    },
  • "roles": [
    ],
  • "subscriptionId": "string",
  • "termsId": "no_terms"
}

User Permissions

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.

Authorizations:
path Parameters
id
required
string

User ID.

Responses

Response samples

Content type
application/json
[
  • "ANALYSES_LOOKUP_OWN"
]

Miscellaneous

OpenAPI specs (HTML)

Gets OpenAPI specification of MythX API, in HTML format.

Responses

Response samples

Content type
application/html
HTML document with OpenAPI specification for MythX API

OpenAPI specs (YAML)

Gets OpenAPI specification of MythX API, in YAML format.

Responses

Response samples

Content type
application/yaml
YAML document with OpenAPI specification for MythX API

API Stats

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.

Authorizations:
path Parameters
type
required
string
Enum: "partners" "users-analyses"

The type of stats to return.

  • detected-issues - Counts of detected issues by SWC type, severity, etc.

  • partners - Statistics on partner-controlled accounts of end users. Currently these include counts of created and activated end user accounts. An account is counted activated at the moment it sends in the first analysis request. Notice that users-analyses stats include counts of analyses submitted from end user accounts controlled by each partner. To fetch these stats users must have STATS_LOOKUP.PARTNERS permission.

  • users-analyses - generic stats on users and analyses that are deduces mostly from scanning analyses collection in API database. Users MUST have STATS_LOOKUP.USERS_ANALYSES permission to fetch these stats.

query Parameters
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 ONE_DAY stats you will get an array of objects, each describing a single day. Other values are self-explanatory.

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 from timestamp.

to
string <date>

Filters requested statistics records by their interval starts, i.e. all returned objects will describe intervals starting prior to timestamp.

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

API version

Gets current versions of MythX API and its core sub-modules.

Responses

Response samples

Content type
application/json
{
  • "api": "v1.2.5",
  • "hash": "c0d8ccbf9ba2623cc147da2860f20093",
  • "harvey": "v0.1.0",
  • "maru": "0.1.0",
  • "mythril": "v1.2.3"
}