logo
Documentation Powered by ReDoc

MythX API (v1.8)

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

200

Returns two objects describing the banner to be shown in the MetaMask dialog and the challenge hash.

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /auth/challenge
https://api.mythx.io/v1/auth/challenge

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    },
  • {
    }
]

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:
MetaMask
Request Body schema: application/json
One of
  • Login with User Credentials
  • Login with MetaMask
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.
jwtLifetimes
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

200

Login successful

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

post /auth/login
https://api.mythx.io/v1/auth/login

Request samples

Content type
application/json
Example
Login with User Credentials
Copy
 Expand all Collapse all
{
  • "password": "pa$$word",
  • "username": "string",
  • "jwtLifetimes":
    {
    },
  • "permissions":
    [
    ],
  • "ethAddress": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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:
JWT
Request Body schema: application/json
global
boolean
Default: false

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

Responses

200

Logged out successfully

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

post /auth/logout
https://api.mythx.io/v1/auth/logout

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "global": false
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

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
jwtTokens
object (JWT Tokens)

Holds a pair of JWT authentication tokens.

accessToken
string
Deprecated

JWT access token.

refreshToken
string
Deprecated

JWT refresh token.

Responses

200

Tokens refreshed successfully

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

post /auth/refresh
https://api.mythx.io/v1/auth/refresh

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "jwtTokens":
    {
    },
  • "accessToken": "string",
  • "refreshToken": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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:
JWT

Responses

200

Success

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /auth/session/permissions
https://api.mythx.io/v1/auth/session/permissions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.

Responses

200

Returns matching groups (up to 20 records a time).

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

403

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

Too many requests — You have either reached the API usage limit allowed to your user and subscription types or the maximum request allowed per client and second.

500

Internal server error — An unexpected error happened at the server side when trying to fulfil your request.

get /analysis-groups
https://api.mythx.io/v1/analysis-groups

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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:
JWT
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

201

Returns the created analysis group

400

Bad Request — Probably an ill-formed request. See error message for details.

401

Unauthorized — Probably an empty or invalid authorization header sent with the request.

403

Unauthorized — Probably an empty or invalid authorization header sent with the request.

429

Too many requests — You have either reached the API usage limit allowed to your user and subscription