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.
|
Returns two objects describing the banner to be shown in the MetaMask dialog and the challenge hash.
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
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.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
[- {
- "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:
|
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 |
userId | string Deprecated An alias of |
Login successful
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
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.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
{- "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. |
Logged out successfully
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
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.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
{- "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.
jwtTokens | object (JWT Tokens) Holds a pair of JWT authentication tokens. |
accessToken | string Deprecated JWT access token. |
refreshToken | string Deprecated JWT refresh token. |
Tokens refreshed successfully
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
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.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
{- "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.
Success
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
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.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
{- "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 |
Returns matching groups (up to 20 records a time).
Bad Request — Probably an ill-formed request. See error
message for details.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
Unauthorized — Probably an empty or invalid authorization header sent with the request.
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.
Internal server error — An unexpected error happened at the server side when trying to fulfil your request.
{- "groups": [
- {
- "id": "string",
- "name": "string",
- "createdAt": "2021-01-15T07:25:00Z",
- "createdBy": "string",
- "completedAt": "2021-01-15T07:25:00Z",
- "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": "string"
}
], - "total": 0
}